Release Process

Releases go through a branch + PR (because main is protected), then a tag push triggers the GitHub Actions release workflow (cargo-dist) that builds cross-platform binaries and creates a GitHub Release.

Prerequisites

Before releasing, verify:

1. All tests pass:

cargo test
cargo clippy -- -D warnings
cargo fmt --check

2. Main branch is clean and up to date:

git checkout main && git pull
git status  # must be clean
git log --oneline -5  # review recent commits

3. CI is green on the latest commit:

gh run list --limit 1

Making a release

Step 1: Create release branch

git checkout -b release/v<version> main

Step 2: Bump version and changelog

Use cog bump with --skip-push (since we can't push directly to main):

cog bump --<level> --skip-push    # or --auto --skip-push

This will:

1. Bump the version in Cargo.toml
2. Generate/update CHANGELOG.md from conventional commits
3. Create a bump commit
4. Create a git tag v<new_version>

If cog bump doesn't support --skip-push, do it manually:

1. Edit Cargo.toml version field
2. Run cog changelog > CHANGELOG.md (or update manually)
3. Commit: git commit -am "chore(release): v<version>"

Step 3: Push branch and create PR

git push -u origin release/v<version>
gh pr create --title "chore(release): v<version>" --body "Version bump and changelog for v<version>"

Wait for CI to pass, then merge the PR.

Step 4: Tag and push

After the PR is merged, tag main and push the tag:

git checkout main && git pull
git tag v<version>
git push origin v<version>

The tag push triggers .github/workflows/release.yml, which builds binaries for macOS, Linux, and Windows, and creates a GitHub Release.

Release levels

Level	Example	Use case
--patch	0.1.0 → 0.1.1	Bug fixes
--minor	0.1.0 → 0.2.0	New features
--major	0.1.0 → 1.0.0	Breaking changes
--minor --pre rc	0.1.0 → 0.2.0-rc.1	Release candidate
--auto	(auto-detected)	Let commits decide

Step 5: Monitor the release build

gh run list --limit 1                  # find the run ID
gh run watch <run-id> --exit-status    # live follow

If a build fails:

gh run view --job=<job-id> --log-failed

After success, verify the GitHub Release:

gh release view v<version>

Configuration

• cog.toml — cocogitto config (tag prefix, bump hooks, changelog, commit validation)
• Cargo.toml — version field, [package.metadata.dist]
• .github/workflows/release.yml — auto-generated by dist generate, do not hand-edit

Important notes

• publish = false — no crates.io publishing. Releases are GitHub-only for now.
• Tag format is v{version} (e.g., v0.1.0), configured by tag_prefix = "v" in cog.toml.
• Prerelease tags (e.g., v0.1.0-rc.1) create a GitHub Release marked as prerelease.
• --auto reads commits since last tag: feat: → minor, fix: → patch, BREAKING CHANGE → major.
• If cargo-dist config changes, regenerate the workflow: dist generate
• Branch protection blocks direct pushes to main — releases always go through a PR. Tags are not blocked.