Release Bump

When to use this skill

Use Release Bump when an AI agent needs a reusable SKILL.md workflow for this job: 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.

When not to use it

Skip Release Bump when the task is outside the productivity category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/release-bump/SKILL.md. For a shared project, commit the folder at .claude/skills/release-bump/ instead.
2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex

What this skill does

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

```bash 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:

```bash 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]`:

```markdown ## [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

```markdown [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.**

```bash git add CHANGELOG.md ```

5. **Run bumpversion.**

```bash 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.**

```bash 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)`

Intended uses

• Verify the working tree is clean (except CHANGELOG.md which may have the draft).
• Determine the bump level.
• Stamp the changelog.
• Change the [Unreleased] link to compare against the new tag
• Add a new link for the new version
• Stage the changelog.
• Run bumpversion.
• 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
• Verify results.
• 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