release-bump

name	release-bump
description	Use this skill to finalize a release. It stamps the [Unreleased] changelog section with a version and date, runs bumpversion to update all version files, and creates the release commit and tag. Only run this when you're ready to ship.

Release Bump

Goal

Finalize the changelog draft, bump the version across all tracked files, and create a tagged release commit. After this skill runs, the repo has a clean release commit and tag ready to push.

Prerequisites

• gh CLI installed and authenticated (gh auth status).
• bumpversion installed (pip install bumpversion or available in the project venv).
• The [Unreleased] section of CHANGELOG.md should already contain the release narrative. If it's empty or stale, run the draft-release-notes skill first.

Workflow

1. Verify the working tree is clean (except CHANGELOG.md which may have the draft).

   git status --porcelain
   

   Only CHANGELOG.md (and optionally .agents/ files) should be modified. If there are other uncommitted changes, stop and ask the user to commit or stash them first.

2. Determine the bump level.

   Ask the user if not specified: patch, minor, or major. Check the current version:

   grep '^current_version' .bumpversion.cfg
   

3. Stamp the changelog.

   Read the current [Unreleased] content from CHANGELOG.md. Compute the new version (based on bump level and current version). Then:

   a. Replace the ## [Unreleased] section body with an empty placeholder. b. Insert a new stamped section immediately after ## [Unreleased]:

   ## [Unreleased]
   
   ## [X.Y.Z] - YYYY-MM-DD
   
   <the content that was in [Unreleased]>
   

   c. Update the reference links at the bottom of the file:

   • Change the [Unreleased] link to compare against the new tag
   • Add a new link for the new version

   [Unreleased]: https://github.com/jamiepine/voicebox/compare/vX.Y.Z...HEAD
   [X.Y.Z]: https://github.com/jamiepine/voicebox/compare/vPREVIOUS...vX.Y.Z
   

4. Stage the changelog.

   git add CHANGELOG.md
   

5. Run bumpversion.

   bumpversion --allow-dirty <patch|minor|major>
   

   The --allow-dirty flag is needed because CHANGELOG.md is already staged. bumpversion will:

   • Update version strings in all tracked files (see .bumpversion.cfg)
   • Create a commit with message Bump version: X.Y.Z -> A.B.C
   • Create a tag vA.B.C

   The staged CHANGELOG.md will be included in this commit automatically.

6. Verify results.

   git show --name-only --stat HEAD
   git tag --list "v*" --sort=-v:refname | head -n 5
   

   Confirm the commit contains:

   • CHANGELOG.md
   • .bumpversion.cfg
   • tauri/src-tauri/tauri.conf.json
   • tauri/src-tauri/Cargo.toml
   • package.json
   • app/package.json
   • tauri/package.json
   • landing/package.json
   • web/package.json
   • backend/__init__.py

   Confirm the new tag exists.

7. Do NOT push unless the user explicitly asks. Report the tag name and suggest:

   Ready to push. When you're ready:
     git push origin main --follow-tags
   

Version Calculation Reference

Given current version X.Y.Z:

• patch -> X.Y.(Z+1)
• minor -> X.(Y+1).0
• major -> (X+1).0.0

Error Recovery

• If bumpversion fails, the tag won't exist. Fix the issue and re-run — bumpversion is idempotent as long as the tag doesn't already exist.
• If you need to undo a release commit (before pushing): git tag -d vX.Y.Z && git reset --soft HEAD~1
• Never amend a release commit that has been pushed.

Notes

• When the tag is pushed, the release CI (.github/workflows/release.yml) automatically extracts the matching version section from CHANGELOG.md and uses it as the GitHub Release body. No manual copy-paste needed.
• The release commit message is controlled by .bumpversion.cfg (Bump version: X.Y.Z -> A.B.C). Do not override it.
• If you need to manually update the GitHub Release body after the fact: gh release edit vX.Y.Z --notes-file <(sed -n '/## \[X.Y.Z\]/,/## \[/p' CHANGELOG.md | head -n -1)