Elgato_dark/datahaven
1
0
Fork 0
mirror of https://github.com/datahaven-xyz/datahaven synced 2026-05-24 09:50:01 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

fix: update docs

Browse source
This commit is contained in:
Gonza Montiel 2026-02-09 15:49:18 -03:00
parent 8e46720e49
commit 8c2b9be90f
2 changed files with 75 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
CLAUDE.md
View file

@ -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

61
contracts/.changesets/README.md
View file

@ -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)