Release Cch

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

[workspace.package]
version = "1.0.0"

Release Trigger: Pushing a tag like v1.0.0 triggers .github/workflows/release.yml

Build Targets:

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

Prerequisites

• Claude CLI installed and in PATH
• CCH binary built (auto-built by test runner)

If Tests Fail

1. Check Claude CLI is installed: which claude
2. Check CCH builds: cd cch_cli && cargo build --release
3. Run with debug: DEBUG=1 ./test/integration/run-all.sh
4. Check logs: ~/.claude/logs/cch.log

For details, see Integration Test README.

Scripts Reference

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