From 6c2d2a9c46925c2ccf3e0c7aa8f860ca46b014af Mon Sep 17 00:00:00 2001 From: Gonza Montiel Date: Mon, 9 Feb 2026 16:28:17 -0300 Subject: [PATCH] docs: add comprehensive versioning documentation Update CLAUDE.md with version management section, contracts/.changesets/README.md with workflow examples, and test/cli/handlers/contracts/README.md with new commands. Document release process and troubleshooting. --- CLAUDE.md | 108 ++++++++++++++++++++++++++ contracts/README.md | 15 ++++ test/cli/handlers/contracts/README.md | 2 +- 3 files changed, 124 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 19e6e5ef..4711ddfe 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -110,6 +110,113 @@ datahaven/ - **Kurtosis**: Orchestrates multi-container test environments - **Parallel Testing**: Use `test:e2e:parallel` for faster CI runs +### Version Management + +DataHaven uses a changeset-based versioning system for contracts with centralized tracking: + +#### Key Files +- **`contracts/VERSION`**: Single source of truth for code version (e.g., `1.0.0`) +- **`contracts/versions-matrix.json`**: Tracks code version + deployed versions across chains +- **`contracts/.changesets/`**: PR-based version bump declarations with descriptions +- **`contracts/deployments/{chain}.json`**: Per-chain deployment info (addresses only) + +#### Developer Workflow + +1. **Make contract changes** in `contracts/src/` + +2. **Declare version bump** (required for CI to pass): + ```bash + bun cli contracts bump --type [major|minor|patch] --description "Brief change description" + ``` + - `major`: Breaking changes (X.0.0) + - `minor`: New features, backwards compatible (0.X.0) + - `patch`: Bug fixes, backwards compatible (0.0.X) + - `--description`: Optional but recommended for clarity in release notes + + This creates a changeset file like `.changesets/pr-123.txt` containing: + - Line 1: Bump type + - Lines 2+: Description (optional) + +3. **Commit changeset**: + ```bash + git add contracts/.changesets/ + git commit -m "feat: your changes" + ``` + +4. **Before release** (manual process): + - Trigger the "Contracts Versioning" GitHub Action manually + - Action processes all accumulated changesets: + - Aggregates multiple major bumps into single major version bump + - Takes highest bump type across all changesets (major > minor > patch) + - Updates `VERSION` file + - Updates `versions-matrix.json` with new checksum + - Creates a PR with version bump and all changeset descriptions + - Deletes processed changesets in the PR + +#### Upgrade/Deploy Commands + +- **Upgrade** (uses VERSION file): + ```bash + bun cli contracts upgrade --chain hoodi --version latest + ``` + - Validates checksum matches `versions-matrix.json` + - Deploys new implementation contracts + - Updates proxy via `upgradeToAndCall` with version update (saves gas) + - Updates `versions-matrix.json` deployment info + - Version is set on-chain during the upgrade transaction (no separate call) + +- **Deploy** (MINOR bump): + ```bash + bun cli contracts deploy --chain anvil + ``` + - Performs MINOR bump automatically + - Updates both deployment file and `versions-matrix.json` + +#### Validation Commands + +- **Check versions across deployments**: + ```bash + bun cli contracts version-check --chain hoodi + ``` + +- **Validate changesets (CI use)**: + ```bash + bun cli contracts validate-changesets + ``` + Fails if contracts changed but no changeset exists + +#### Version Matrix Structure + +```json +{ + "code": { + "version": "1.0.0", // Current code version + "checksum": "abc123...", // SHA1 of contracts/src/ + "lastModified": "2026-02-05T..." + }, + "deployments": { + "anvil": { "version": "0.1.0", "lastDeployed": "..." }, + "hoodi": { "version": "1.0.0", "lastDeployed": "..." } + } +} +``` + +#### Release Process + +1. **Accumulate changesets**: Multiple PRs with contract changes create changeset files +2. **Trigger version bump**: Manually run "Contracts Versioning" GitHub Action +3. **Review PR**: Action creates PR with: + - Updated VERSION and versions-matrix.json + - All changeset descriptions in PR body + - Deleted changeset files +4. **Upgrade contracts**: Checkout PR branch and run `bun cli contracts upgrade` +5. **Merge PR**: Complete the release by merging to main + +#### If Version Out of Sync (Rare) +1. **Checksum mismatch**: Run `bun cli contracts apply-changesets` locally or update VERSION manually +2. **On-chain sync**: Upgrade command automatically sets version via `upgradeToAndCall` +3. **Generated reference**: Not used (versions are tracked in `versions-matrix.json`) + ### Development Workflow 1. Make changes to relevant component 2. Run component-specific tests and linters @@ -124,6 +231,7 @@ datahaven/ - **Types mismatch**: Regenerate with `bun generate:types` after runtime changes - **Kurtosis not running**: Ensure Docker is running and Kurtosis engine is started - **Contract changes not reflected**: Run `bun generate:wagmi` after modifications +- **Version out of sync**: Run `bun cli contracts apply-changesets` (CI) or update `VERSION` manually - **Forge build errors**: Try `forge clean` then rebuild - **Slow development cycle**: Use `--features fast-runtime` for faster block times - **Network launch halts**: Check Blockscout - forge output can appear frozen diff --git a/contracts/README.md b/contracts/README.md index 9a737048..e0f9cd73 100644 --- a/contracts/README.md +++ b/contracts/README.md @@ -61,6 +61,21 @@ NETWORK=hoodi forge script script/deploy/DeployTestnet.s.sol \ ``` Supported networks: `hoodi` (no mainnet config yet). Artifacts → `contracts/deployments/.json`. +### Contract versioning (version) + +DataHaven uses a changeset-based versioning system with centralized tracking: + +- `contracts/VERSION` is the single source of truth for the code version. +- `contracts/versions-matrix.json` tracks the code version and per-chain deployments. +- `contracts/deployments/.json` contains addresses only (no version field). +- Version is **passed as a parameter** during contract deployment (not hardcoded by chain ID). +- Version management is **changeset-driven**: + - `bun cli contracts bump --type [major|minor|patch]` creates a changeset + - CI applies changesets and updates `VERSION` + `versions-matrix.json` +- Multiple environments can share the same deployment file: + - `stagenet-hoodi` and `testnet-hoodi` both write to `hoodi.json` (chainId: 560048) +- For validation, run `bun cli contracts version-check --chain ` and `bun cli contracts validate-changesets`. + ## How It Works 1. **Registration**: Validators register with EigenLayer via `DataHavenServiceManager`. 2. **Performance Tracking**: DataHaven computes reward points and sends a Merkle root to `RewardsRegistry` on Ethereum via Snowbridge. diff --git a/test/cli/handlers/contracts/README.md b/test/cli/handlers/contracts/README.md index 08307513..6aa004d1 100644 --- a/test/cli/handlers/contracts/README.md +++ b/test/cli/handlers/contracts/README.md @@ -62,4 +62,4 @@ bun cli contracts status --chain hoodi Successful deployments create: - `../contracts/deployments/{chain}.json` - Contract addresses -- `../contracts/deployments/{chain}-rewards-info.json` - Rewards configuration \ No newline at end of file + \ No newline at end of file