release

Release Process

Turn the Conventional Commits since the last tag into a versioned release: a bumped CHANGELOG.md, package manifest updates, an annotated git tag, and a GitHub release. Uses git-cliff (config: dot_config/git-cliff/cliff.toml, deployed to ~/.config/git-cliff/cliff.toml).

Authority Boundaries

• Preparing or reviewing a release does not authorize a commit, tag, push, GitHub release, asset upload, package or image publication, deployment, or announcement. Confirm each requested external mutation before performing it.
• Verification is read-only apart from downloading public assets into a disposable directory. It never creates or edits a release, moves a tag, replaces an asset, rebuilds an artifact, or resigns it.
• If a repository workflow owns release creation, let the pushed tag trigger that workflow and verify its result; do not race it with gh release create.

Publication Preconditions

• Clean working tree on the default branch (main), synced with origin.
• History follows conventional-commit — git-cliff groups commits by type and skips chore(release)/chore(deps).
• The repository's full gate passes on the release tree, normally mise run all. Before running it, inspect the full gate's task definition and working-tree state. If it invokes whole-tree write-formatters or the tree contains unrelated changes, use an isolated temporary worktree; never reformat unrelated work.
• The proposed tag is absent locally and remotely. Stop if either copy exists; never move a published tag.

Workflow

1. Compute the next version from the commit types since the last tag (feat → minor, fix/others → patch, !/BREAKING CHANGE → major):

   # Resolves the local/global cliff.toml configuration
   git-cliff --bumped-version
   
   # Or explicitly reference the global config if a local one is not present:
   git-cliff --config ~/.config/git-cliff/cliff.toml --bumped-version
   

2. Update package manifests (if the project doesn't use dynamic/VCS-based versioning) to match the computed version (e.g., vX.Y.Z or X.Y.Z):

   • Python: Bump version in pyproject.toml (unless using dynamic versioning via hatch-vcs or similar).
   • Node.js: Run npm version --no-git-tag-version X.Y.Z or update package.json.
   • Go / OpenTofu: Versioned via git tags (no file changes needed).

3. Generate the changelog for that version (pass --config to be explicit):

   git-cliff --config ~/.config/git-cliff/cliff.toml --bump -o CHANGELOG.md
   

4. Commit the changelog and manifest changes with a release commit (excluded from the changelog by design):

   git add CHANGELOG.md
   # plus the manifest you bumped in step 2, if any (Python: pyproject.toml · Node: package.json · Go/OpenTofu: none)
   git commit -m "chore(release): vX.Y.Z"
   

5. Record, tag, and push the exact release commit after the authorized release commit:

   tag=vX.Y.Z
   release_sha=$(git rev-parse HEAD)
   git tag -a "$tag" -m "$tag" "$release_sha"
   git push --atomic origin main "refs/tags/$tag"
   

6. Publish the GitHub release using only the latest section as notes (write to a temp file to stay shell-agnostic):

   release_tmp=$(mktemp -d)
   git-cliff --config ~/.config/git-cliff/cliff.toml --latest --strip all > "$release_tmp/release-notes.md"
   gh release create "$tag" --verify-tag --title "$tag" --notes-file "$release_tmp/release-notes.md"
   

7. Print the release URL and the resolved version.