Prepare a versioned release: bump version, finalise changelog, commit, and tag.
Prepare and tag a release following project conventions.
Before starting a release:
[Unreleased] section in CHANGELOG.md must
have content. If it is empty, warn the user and ask
whether to proceed with an empty release.Inspect the current state
Run in parallel:
git status — verify clean working tree.Cargo.toml — get current version.CHANGELOG.md — check [Unreleased]
section has entries.git tag --list 'v*' — list existing tags to
avoid conflicts.Determine the new version
If the user passed a version or bump level as an
argument, use it. Otherwise, analyse the
[Unreleased] changelog entries and suggest:
[Unreleased] contains breaking
changes to CLI interface or JSON output schema.Added entries (new
subcommands, flags, features).Fixed, Changed,
or Removed entries with no new features.Present the suggestion and ask the user to confirm or override.
Accepted argument formats:
major, minor, patch1.2.3 (without v prefix)Update Cargo.toml
Change the version field to the new version.
Run cargo check to regenerate Cargo.lock.
Update CHANGELOG.md
## [Unreleased] to
## [X.Y.Z] - YYYY-MM-DD (today's date).## [Unreleased] section above it
with no entries.Run quality gates
cargo xtask validate
If any check fails, stop and fix before continuing.
Stage and commit
Stage the modified files:
git add Cargo.toml Cargo.lock CHANGELOG.md
Commit with message:
chore(release): vX.Y.Z
AI-Generated: Claude Code (<ModelName> <Date>)
Use a heredoc for correct formatting.
Create the tag
git tag -a vX.Y.Z -m "vX.Y.Z"
Use an annotated tag (not lightweight) so it
shows in git describe and triggers the release
workflow.
Verify
Run in parallel:
git status — confirm clean tree.git log --oneline -3 — confirm release commit.git tag --list 'v*' — confirm tag exists.Report the commit hash, version, and tag to the user.
Remind about push
Tell the user:
Ready to publish. Push commit and tag with:
git push && git push --tags
Do not push automatically — let the user decide.
vX.Y.Z already
exists, stop and ask the user.git tag -a).vX.Y.Z (with v prefix) to
match the release.yml workflow trigger.