release-cch
Contents
- •Overview
- •Decision Tree
- •Phase 1: Prepare Release
- •Phase 2: Execute Release
- •Phase 3: Verify Release
- •Phase 4: Hotfix Release
- •Scripts Reference
- •References
Overview
Single Source of Truth: Version is stored in Cargo.toml (workspace root):
toml
[workspace.package] version = "1.0.0"
Release Trigger: Pushing a tag like v1.0.0 triggers .github/workflows/release.yml
Build Targets:
| Platform | Target | Asset |
|---|---|---|
| Linux x86_64 | x86_64-unknown-linux-gnu | cch-linux-x86_64.tar.gz |
| Linux ARM64 | aarch64-unknown-linux-gnu | cch-linux-aarch64.tar.gz |
| macOS Intel | x86_64-apple-darwin | cch-macos-x86_64.tar.gz |
| macOS Apple Silicon | aarch64-apple-darwin | cch-macos-aarch64.tar.gz |
| Windows | x86_64-pc-windows-msvc | cch-windows-x86_64.exe.zip |
Repository: SpillwaveSolutions/code_agent_context_hooks
Decision Tree
code
What do you need? | +-- Starting a new release? --> Phase 1: Prepare Release | +-- PR merged, ready to tag? --> Phase 2: Execute Release | +-- Tag pushed, checking status? --> Phase 3: Verify Release | +-- Need to patch an existing release? --> Phase 4: Hotfix Release | +-- Something went wrong? --> references/troubleshooting.md
Phase 1: Prepare Release
1.1 Read Current Version
bash
# Run from repo root .opencode/skill/release-cch/scripts/read-version.sh # Output: 1.0.0
1.2 Determine New Version
Follow semantic versioning:
- •MAJOR (X.0.0): Breaking changes
- •MINOR (x.Y.0): New features, backwards compatible
- •PATCH (x.y.Z): Bug fixes only
Update Cargo.toml (manual step):
toml
[workspace.package] version = "1.1.0" # <- Update this
1.3 Create Release Branch
bash
VERSION=$(.opencode/skill/release-cch/scripts/read-version.sh)
git checkout -b release/v${VERSION}
1.4 Run Pre-flight Checks
bash
.opencode/skill/release-cch/scripts/preflight-check.sh
This validates:
- • Clean working directory (or only release files modified)
- • All unit tests pass (
cargo test) - • All integration tests pass (
task integration-test) - • Clippy has no warnings
- • Format check passes
IMPORTANT: Integration tests are REQUIRED before any release. They validate that CCH works correctly with the real Claude CLI end-to-end. If Claude CLI is not installed, the preflight check will warn but not block - however, you should ensure integration tests pass in CI before releasing.
1.5 Generate Changelog
bash
VERSION=$(.opencode/skill/release-cch/scripts/read-version.sh)
.opencode/skill/release-cch/scripts/generate-changelog.sh ${VERSION}
Review the output and update CHANGELOG.md as needed. The script parses conventional commits (feat:, fix:, docs:, chore:).
1.6 Commit and Push
bash
VERSION=$(.opencode/skill/release-cch/scripts/read-version.sh)
git add CHANGELOG.md Cargo.toml
git commit -m "chore: prepare v${VERSION} release"
git push -u origin release/v${VERSION}
1.7 Create Release PR
bash
VERSION=$(.opencode/skill/release-cch/scripts/read-version.sh)
gh pr create \
--title "chore: prepare v${VERSION} release" \
--body "$(cat <<EOF
## Summary
Prepare for the v${VERSION} release of Claude Context Hooks (CCH).
## Changes
- Update version to ${VERSION} in Cargo.toml
- Add CHANGELOG.md entry for v${VERSION}
## Pre-merge Requirements
Before merging this PR, ensure:
- [ ] All CI checks pass (including integration tests)
- [ ] Integration tests verified locally: \`task integration-test\`
## Release Checklist
After this PR is merged:
1. Checkout main: \`git checkout main && git pull\`
2. Create tag: \`git tag v${VERSION}\`
3. Push tag: \`git push origin v${VERSION}\`
This will trigger the release workflow to build cross-platform binaries:
- Linux (x86_64, aarch64)
- macOS (x86_64, aarch64/Apple Silicon)
- Windows (x86_64)
EOF
)"
1.8 Wait for CI
bash
gh pr checks <PR_NUMBER> --watch
All checks must pass before merging:
- •Format, Clippy, Unit Tests, Code Coverage
- •Integration Tests (CCH + Claude CLI end-to-end validation)
- •Build Release (5 platforms)
- •CI Success
Note: Integration tests validate that CCH hooks work correctly with the real Claude CLI. These are critical gate checks - do NOT skip them.
Phase 2: Execute Release
2.1 Merge the Release PR
bash
gh pr merge <PR_NUMBER> --merge --delete-branch
2.2 Sync Local Main
bash
git checkout main git pull
2.3 Create and Push Tag
bash
VERSION=$(.opencode/skill/release-cch/scripts/read-version.sh)
git tag v${VERSION}
git push origin v${VERSION}
This triggers the release workflow automatically.
Phase 3: Verify Release
3.1 Monitor Workflow
bash
.opencode/skill/release-cch/scripts/verify-release.sh
Or manually:
bash
gh run list --limit 3 gh run view <RUN_ID> --watch
3.2 Verify Release Assets
bash
VERSION=$(.opencode/skill/release-cch/scripts/read-version.sh)
gh release view v${VERSION}
Expected assets (6 total):
- •cch-linux-x86_64.tar.gz
- •cch-linux-aarch64.tar.gz
- •cch-macos-x86_64.tar.gz
- •cch-macos-aarch64.tar.gz
- •cch-windows-x86_64.exe.zip
- •checksums.txt
3.3 Announce Release
Once verified, the release is live at:
code
https://github.com/SpillwaveSolutions/code_agent_context_hooks/releases/tag/v${VERSION}
Phase 4: Hotfix Release
Use this when you need to release a patch (e.g., v1.0.1) from an existing release tag.
4.1 Create Hotfix Branch from Tag
bash
# Checkout the tag you want to patch git fetch --tags git checkout v1.0.0 # Create hotfix branch git checkout -b hotfix/v1.0.1
4.2 Apply Fix
Make the minimal fix needed, then run checks:
bash
cd cch_cli && cargo fmt && cargo clippy --all-targets --all-features -- -D warnings && cargo test
4.3 Update Version
Edit Cargo.toml at the workspace root:
toml
[workspace.package] version = "1.0.1"
4.4 Update Changelog
Add entry to CHANGELOG.md:
markdown
## [1.0.1] - YYYY-MM-DD ### Fixed - Description of the hotfix
4.5 Commit and Push
bash
git add -A git commit -m "fix: <description of hotfix> Hotfix for v1.0.0 addressing <issue description>" git push -u origin hotfix/v1.0.1
4.6 Create PR to Main
bash
gh pr create \ --title "fix: hotfix v1.0.1" \ --body "## Hotfix Release Patches v1.0.0 with critical fix for <issue>. ### Changes - <description> ### Release Steps After Merge 1. \`git checkout main && git pull\` 2. \`git tag v1.0.1\` 3. \`git push origin v1.0.1\`"
4.7 After PR Merge - Tag and Release
bash
gh pr merge <PR_NUMBER> --merge --delete-branch git checkout main && git pull git tag v1.0.1 git push origin v1.0.1
4.8 Verify Hotfix Release
bash
.opencode/skill/release-cch/scripts/verify-release.sh 1.0.1
Integration Tests (Required)
Integration tests validate CCH works correctly with the real Claude CLI. These must pass before any release.
Running Integration Tests
bash
# Via Taskfile (recommended) task integration-test # Or directly ./test/integration/run-all.sh # Quick mode (skip slow tests) task integration-test-quick # Single test ./test/integration/run-all.sh --test 01-block-force-push
Test Cases
| Test | What It Validates |
|---|---|
01-block-force-push | CCH blocks dangerous git operations |
02-context-injection | CCH injects context for file types |
03-session-logging | CCH creates proper audit logs |
04-permission-explanations | CCH provides permission context |
Prerequisites
- •Claude CLI installed and in PATH
- •CCH binary built (auto-built by test runner)
If Tests Fail
- •Check Claude CLI is installed:
which claude - •Check CCH builds:
cd cch_cli && cargo build --release - •Run with debug:
DEBUG=1 ./test/integration/run-all.sh - •Check logs:
~/.claude/logs/cch.log
For details, see Integration Test README.
Scripts Reference
| Script | Purpose | Usage |
|---|---|---|
read-version.sh | Extract version from Cargo.toml | ./scripts/read-version.sh |
generate-changelog.sh | Generate changelog from commits | ./scripts/generate-changelog.sh [version] |
preflight-check.sh | Run all pre-release checks (includes integration tests) | ./scripts/preflight-check.sh [--json] |
verify-release.sh | Monitor release workflow status | ./scripts/verify-release.sh [version] |
All scripts are located in .opencode/skill/release-cch/scripts/.
References
- •release-workflow.md - Standard release workflow diagram
- •hotfix-workflow.md - Hotfix release workflow diagram
- •troubleshooting.md - Common issues and solutions
Quick Command Reference
Standard Release
bash
# 1. Update version in Cargo.toml manually
# 2. Create release branch
VERSION=$(.opencode/skill/release-cch/scripts/read-version.sh)
git checkout -b release/v${VERSION}
# 3. Run checks
.opencode/skill/release-cch/scripts/preflight-check.sh
# 4. Generate changelog, review, commit
.opencode/skill/release-cch/scripts/generate-changelog.sh ${VERSION}
# Edit CHANGELOG.md as needed
git add CHANGELOG.md Cargo.toml
git commit -m "chore: prepare v${VERSION} release"
git push -u origin release/v${VERSION}
# 5. Create and merge PR
gh pr create --title "chore: prepare v${VERSION} release" --body "..."
gh pr checks <PR> --watch
gh pr merge <PR> --merge --delete-branch
# 6. Tag and release
git checkout main && git pull
git tag v${VERSION}
git push origin v${VERSION}
# 7. Verify
.opencode/skill/release-cch/scripts/verify-release.sh
Hotfix Release
bash
# 1. Branch from tag git checkout v1.0.0 git checkout -b hotfix/v1.0.1 # 2. Fix, update version, update changelog # 3. Commit, push, PR, merge # 4. Tag and release git checkout main && git pull git tag v1.0.1 git push origin v1.0.1