From 8c2b9be90f5320af821cf82606d837d694324b7e Mon Sep 17 00:00:00 2001 From: Gonza Montiel Date: Mon, 9 Feb 2026 15:49:18 -0300 Subject: [PATCH] fix: update docs --- CLAUDE.md | 44 +++++++++++++++++------- contracts/.changesets/README.md | 61 ++++++++++++++++++++++++--------- 2 files changed, 75 insertions(+), 30 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 1f08aabd..4711ddfe 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -117,7 +117,7 @@ DataHaven uses a changeset-based versioning system for contracts with centralize #### 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 (processed by CI) +- **`contracts/.changesets/`**: PR-based version bump declarations with descriptions - **`contracts/deployments/{chain}.json`**: Per-chain deployment info (addresses only) #### Developer Workflow @@ -126,13 +126,16 @@ DataHaven uses a changeset-based versioning system for contracts with centralize 2. **Declare version bump** (required for CI to pass): ```bash - bun cli contracts bump --type [major|minor|patch] + 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` + This creates a changeset file like `.changesets/pr-123.txt` containing: + - Line 1: Bump type + - Lines 2+: Description (optional) 3. **Commit changeset**: ```bash @@ -140,13 +143,15 @@ DataHaven uses a changeset-based versioning system for contracts with centralize git commit -m "feat: your changes" ``` -4. **On merge to main**: GitHub Actions automatically: - - Reads all changeset files - - Takes highest bump type (major > minor > patch) - - Updates `VERSION` file - - Updates `versions-matrix.json` with new checksum - - Deletes processed changesets - - Commits changes to main +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 @@ -155,8 +160,10 @@ DataHaven uses a changeset-based versioning system for contracts with centralize bun cli contracts upgrade --chain hoodi --version latest ``` - Validates checksum matches `versions-matrix.json` - - Updates deployment file and on-chain version + - 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 @@ -194,9 +201,20 @@ DataHaven uses a changeset-based versioning system for contracts with centralize } ``` +#### 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` or update VERSION manually -2. **On-chain sync**: Upgrade command automatically calls `updateVersion()` on ServiceManager +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 diff --git a/contracts/.changesets/README.md b/contracts/.changesets/README.md index 61070de8..f7213707 100644 --- a/contracts/.changesets/README.md +++ b/contracts/.changesets/README.md @@ -7,20 +7,24 @@ This directory contains version bump declarations for contract changes. When you modify contracts in `contracts/src/`, you must declare a version bump by running: ```bash -bun cli contracts bump --type [major|minor|patch] +bun cli contracts bump --type [major|minor|patch] --description "Optional description" ``` -This creates a file like `pr-123.txt` (or `bump-{timestamp}.txt` if not in a PR) containing the bump type. +This creates a file like `pr-123.txt` (or `bump-{timestamp}.txt` if not in a PR) containing: +- First line: The bump type +- Subsequent lines: Optional description of the changes -## On Merge to Main +## Release Workflow -A GitHub Action automatically: -1. Reads all changeset files -2. Determines the highest bump type (major > minor > patch) -3. Updates the `VERSION` file accordingly -4. Updates `versions-matrix.json` -5. Deletes all changeset files -6. Commits the changes +1. **Development**: Developers create changesets for their contract changes +2. **Before Release**: Manually trigger the "Contracts Versioning" GitHub Action +3. **PR Creation**: The action creates a PR with: + - Updated `VERSION` file + - Updated `versions-matrix.json` + - All changeset descriptions in PR body + - Deleted changeset files +4. **Contract Upgrade**: Checkout the PR branch and run `bun cli contracts upgrade` +5. **Merge**: Merge the PR to main after upgrade completes ## Example Workflow @@ -28,29 +32,52 @@ A GitHub Action automatically: # 1. Make contract changes vim contracts/src/DataHavenServiceManager.sol -# 2. Declare version bump -bun cli contracts bump --type minor +# 2. Declare version bump with description +bun cli contracts bump --type minor --description "Add support for custom validator rewards" # 3. Commit the changeset file git add contracts/.changesets/ -git commit -m "feat: add new feature" +git commit -m "feat: add custom validator rewards" # 4. Push PR - CI validates changeset exists git push origin feature-branch -# 5. On merge to main, GitHub Action processes changesets automatically +# 5. On merge to main, changesets accumulate + +# 6. Before release, manually run GitHub Action "Contracts Versioning" + +# 7. Action creates PR with version bump + +# 8. Checkout PR and upgrade contracts +git checkout release/version-X.Y.Z +bun cli contracts upgrade --chain hoodi + +# 9. Merge PR to main ``` ## File Format -Each changeset file contains a single line with the bump type: +Each changeset file contains: +- **Line 1**: Bump type (`major`, `minor`, or `patch`) +- **Lines 2+**: Optional description of changes + +Example `pr-123.txt`: +``` +minor +Add support for custom validator rewards distribution. +This allows operators to configure reward multipliers per validator. +``` + +## Version Bump Rules + - `major` - Breaking changes (X.0.0) - `minor` - New features, backwards compatible (0.X.0) - `patch` - Bug fixes, backwards compatible (0.0.X) -## Rules +## Aggregation Rules -- One changeset file per PR +- One or more changeset files per PR - CI fails if contracts changed but no changeset exists - Multiple changesets are consolidated by taking the highest bump type +- **Multiple major bumps are aggregated into a single major version bump** - Changesets are deleted after processing (clean main branch)