| name | releasing |
| description | Guides the semantic versioning release workflow. Invoke when the user asks to tag, release, cut a release, bump the version, or publish a new version. Determines the next semver version, presents it for user approval, then tags and pushes. Monitors the release CI workflow to completion. |
Releasing a New Version
This project uses semantic versioning and GoReleaser. Releases are triggered by pushing a Git tag — CI builds binaries and updates the Homebrew tap automatically. Do not run GoReleaser locally.
Workflow
1. Pre-flight checks
Verify the environment is ready. Do not proceed until all checks pass.
git branch --show-current
git status --porcelain
git fetch origin
git status -uno
- Must be on the default branch
- Working tree must be clean (no uncommitted changes)
- Local branch must be up to date with the remote
If dirty, commit or stash first. If behind, pull before proceeding.
2. Determine the current version
git fetch --tags origin
git tag --sort=-v:refname | head -5
Identify the latest vX.Y.Z tag. This is the baseline for the next version.
3. Analyze changes and build a changelog
git log <latest-tag>..HEAD --oneline
Group commits into categories:
- Features: new capabilities, commands, integrations
- Fixes: bug fixes, crash fixes, correctness improvements
- Internal: refactoring, docs, CI, dependency updates
Classify the overall change scope:
| Change type | Version bump | Examples |
|---|
| Breaking or incompatible changes | Major (X.0.0), or Minor while pre-1.0 | Removed a command, changed config schema incompatibly |
| New features or capabilities | Minor (0.X.0) | Added a subcommand, new config option |
| Bug fixes, docs, internal | Patch (0.0.X) | Fixed a crash, corrected a typo, refactored internals |
While the project is pre-1.0, breaking changes bump minor (not major).
4. Present the proposed version — then stop
Present the user with:
- The changelog summary
- The suggested version with reasoning
- The commit that will be tagged (short SHA + first line)
**STOP.** Wait for the user to explicitly confirm or override the version number. Do not tag until the user states the version they want.
The user decides the version — your suggestion is advisory. If the user picks a different version, use theirs.
5. Tag and push
Verify the tag does not already exist:
git tag -l v<confirmed-version>
If it exists, ask the user for a different version. Otherwise:
git tag v<confirmed-version>
git push origin v<confirmed-version>
6. Verify the release
The tag push triggers .github/workflows/release.yml, which runs GoReleaser to build binaries and update the Homebrew tap.
Monitor until complete:
gh run list --workflow=release.yml --limit=1
If still in progress, stream logs:
gh run watch <run-id>
The release is not done until the workflow reports success. If it fails, investigate and resolve before telling the user the release is complete.
When successful, confirm with:
- The version released
- A link to the GitHub release page
- A reminder that
brew upgrade project-replaceme will pick up the new version
