Cut a Release

A release is a promise to users: this version number means what semantic versioning says it means, the changelog tells them what changed and what they must do, and the artifact they install is the one you tested. Most public registries never let you reuse a version number, so mistakes are permanent; you check twice and publish once.

When to use

• "Ship 2.4", "tag a release", "publish the new version to npm or PyPI", "write the changelog", "draft release notes".
• A release workflow failed halfway and needs finishing.
• A bad release needs a follow-up patch release or a yank.

What you need

• The repo with tags fetched (git fetch --tags origin), and its release process: RELEASING.md, a release workflow in CI, or a tool the project already uses (release-please, semantic-release, changesets, goreleaser, cargo-release, bump-my-version).
• Access to the hosting and registry: the GitHub or GitLab connected app, or the browser signed in by the owner. Registry publishing normally runs in CI with tokens stored as CI secrets; never ask for or paste registry tokens into chat or commands.
• The owner's go-ahead for anything public: pushing a release tag (it often triggers publishing), publishing to a registry, posting announcements.

Method

1. Check readiness.

   • The default branch is green in CI on the commit you will release.
   • No open issues or PRs labelled as release blockers (ask the owner if unsure).
   • The working tree is clean and up to date: git status, git pull --ff-only.

2. Collect what changed.

   LAST=$(git describe --tags --abbrev=0)
   git log --oneline --no-merges "$LAST"..HEAD
   gh pr list --state merged --base main --search "merged:>=$(git log -1 --format=%cs "$LAST")" --limit 200
   

   Read each PR title and description; open the diff when the effect on users is unclear.

3. Choose the version (semantic versioning, MAJOR.MINOR.PATCH).

   Change since last release	Bump
   Anything that can break existing users: removed or renamed public API, changed defaults, changed output formats, stricter validation, dropped runtime or platform support, required config changes	MAJOR
   New backward-compatible features or options; deprecations	MINOR
   Backward-compatible bug fixes only	PATCH
   Before 1.0.0, the project's own convention rules (many treat 0.MINOR as breaking); state which you followed. Pre-releases use suffixes such as 2.0.0-rc.1. If you are unsure whether something breaks users, treat it as breaking and ask the owner.

4. Write the changelog entry. Use the project's existing format, or the Keep a Changelog layout in references/changelog-format.md: newest first, a dated version heading, and sections Added, Changed, Deprecated, Removed, Fixed, Security. Write for users, not for the team: "Exports now include the invoice currency" rather than "refactor exporter". Link PRs or issues. Breaking changes get their own clearly marked list with the migration steps.

5. Bump every version string. Use the project's tool if it has one (npm version 2.4.0 --no-git-tag-version, poetry version 2.4.0, uv version 2.4.0, cargo set-version 2.4.0 with cargo-edit). Then search_files for the old version string to catch stragglers: pyproject.toml, package.json (and lockfile metadata), Cargo.toml, __version__, version.go, Helm Chart.yaml, docs and install snippets. Do not touch dependency version strings that merely happen to match.

6. Build and test the release candidate locally. Run the full suite and build the artifact exactly as the release pipeline does (python -m build, npm pack, cargo package, goreleaser release --snapshot --clean, docker build). Inspect it: tar -tzf dist/*.tar.gz | head, npm pack --dry-run lists the files that would ship. Look for missing files and for files that must not ship (tests with secrets, .env, large fixtures).

7. Commit and tag (local first).

   git add CHANGELOG.md pyproject.toml src/pkg/__init__.py
   git commit -m "chore(release): v2.4.0"
   git tag -a v2.4.0 -m "v2.4.0"
   

   Use the repo's tag format (v2.4.0 or 2.4.0, or [email protected] in monorepos). The tag must match the version in the files.

8. Get the go-ahead, then publish. Show the owner a show_card with the version, the bump reason, the changelog entry and what will happen when the tag is pushed. On approval:

   git push origin main && git push origin v2.4.0
   gh release create v2.4.0 --title "v2.4.0" --notes-file notes.md            # if not done by CI
   

   Let the CI release workflow publish to the registry where one exists; watch it (gh run watch). Manual publishing (npm publish, twine upload or uv publish, cargo publish) only if that is the project's documented process and the owner approved it.

9. Verify what was published. In a clean environment (a fresh virtualenv, an empty directory, a new container):

   python -m venv /tmp/rel && /tmp/rel/bin/pip install "pkg==2.4.0" && /tmp/rel/bin/python -c "import pkg; print(pkg.__version__)"
   npm view [email protected] version && cd "$(mktemp -d)" && npm init -y >/dev/null && npm install [email protected]
   docker pull ghcr.io/org/app:2.4.0 && docker run --rm ghcr.io/org/app:2.4.0 --version
   

   Run a short smoke test of the main feature. Check the release page and changelog render correctly.

10. Announce. Release notes for users: two or three highlights, breaking changes with migration steps, the upgrade command, and a link to the full changelog. Post only where the owner wants it posted.

11. If the release is bad. Do not delete or move a published tag others may have pulled, and you cannot reuse the version number on most registries. Mark the bad version (npm deprecate [email protected] "use 2.4.1", yank on PyPI through its web page, cargo yank --version 2.4.0), with the owner's go-ahead, and ship a patch release with the fix.

Output

The release (tag, GitHub or GitLab release, published artifact) and a note to the owner: version and why that bump, the changelog entry, where it was published, the verification you ran on the published artifact, and any follow-ups. If you stopped before publishing, the prepared commit and tag, and exactly what remains.

Checks before you finish

• CI was green on the released commit, and the full suite and build passed locally.
• The version bump follows the semantic versioning table, with breaking changes called out.
• Every version string matches the tag.
• The artifact was inspected before publishing and installed and smoke-tested after.
• Publishing and tag pushes happened only with the owner's go-ahead.

Pitfalls

• A breaking change in a minor release. Users pin to ^2.3 and break. When in doubt, it is breaking.
• Changelogs that list commits. Users need effects and actions, not "fix typo" and "bump deps".
• Missed version strings. The package says 2.4.0 and --version says 2.3.1.
• Publishing from a dirty or unreviewed tree. Release from a clean checkout of the tagged commit.
• Unpublish and republish. Registries keep version numbers burned. Ship a patch instead.
• Pushing the tag "to test". Tag pushes often publish. Treat them as the release.