release-cch

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

[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

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

# 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):

[workspace.package]
version = "1.1.0"  # <- Update this

1.3 Create Release Branch

VERSION=$(.opencode/skill/release-cch/scripts/read-version.sh)
git checkout -b release/v${VERSION}

1.4 Run Pre-flight Checks

.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

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

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

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

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

gh pr merge <PR_NUMBER> --merge --delete-branch

2.2 Sync Local Main

git checkout main
git pull

2.3 Create and Push Tag

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

.opencode/skill/release-cch/scripts/verify-release.sh

Or manually:

gh run list --limit 3
gh run view <RUN_ID> --watch

3.2 Verify Release Assets

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:

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

# 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:

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:

[workspace.package]
version = "1.0.1"

4.4 Update Changelog

Add entry to CHANGELOG.md:

## [1.0.1] - YYYY-MM-DD

### Fixed

- Description of the hotfix

4.5 Commit and Push

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

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

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

.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

# 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

# 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

# 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

release-cch

release-cch

Contents

Overview

Decision Tree

Phase 1: Prepare Release

1.1 Read Current Version

1.2 Determine New Version

1.3 Create Release Branch

1.4 Run Pre-flight Checks

1.5 Generate Changelog

1.6 Commit and Push

1.7 Create Release PR

1.8 Wait for CI

Phase 2: Execute Release

2.1 Merge the Release PR

2.2 Sync Local Main

2.3 Create and Push Tag

Phase 3: Verify Release

3.1 Monitor Workflow

3.2 Verify Release Assets

3.3 Announce Release

Phase 4: Hotfix Release

4.1 Create Hotfix Branch from Tag

4.2 Apply Fix

4.3 Update Version

4.4 Update Changelog

4.5 Commit and Push

4.6 Create PR to Main

4.7 After PR Merge - Tag and Release

4.8 Verify Hotfix Release

Integration Tests (Required)

Running Integration Tests

Test Cases

Prerequisites

If Tests Fail

Scripts Reference

References

Quick Command Reference

Standard Release

Hotfix Release