Release Version

Bump the version everywhere it lives, record what changed, tag it. Stop before publishing.

1. Find where the version lives

Detect the ecosystem rather than assuming one. Use the native tool where there is one — it keeps lockfiles and metadata in sync, which hand-editing does not.

Not listed, or a project that keeps the version in several places? Grep the current version string across tracked files and treat every hit as a candidate:

git grep -nF 1.2.3 -- . ':!*.lock' ':!CHANGELOG*'   # the current version

Docs, README badges, Helm Chart.yaml, CITATION.cff, Dockerfiles, and constants files all hide copies. A release that updates the manifest and misses __version__ ships a package that lies about itself.

Monorepo with several packages? Bump only what actually changed, and say which. Ask before bumping them all in lockstep unless the repo clearly already does that.

2. Choose the bump

Read the real changes since the last tag, not the last commit alone:

git describe --tags --abbrev=0 && git log $(git describe --tags --abbrev=0)..HEAD --oneline

Semver, decided by what a consumer experiences:

• major — a breaking change: removed or renamed public API, changed defaults, changed output format, raised the minimum runtime.
• minor — new capability, backwards compatible.
• patch — fix, docs, internals; nothing a caller must react to.

Below 1.0.0, breaking changes conventionally land in minor (0.4.0 → 0.5.0). Say which rule you applied and why, in one line — a bump the user disagrees with is cheap to fix before the tag and expensive after.

Pre-release? 1.2.0-rc.1, and remember most registries treat it as non-default.

3. Apply it

Run the native command, then verify nothing stale is left:

git grep -nF "<old version>" -- . ':!CHANGELOG*'

Lockfiles must be regenerated by their own tool, never edited by hand.

4. Changelog

If the project has a CHANGELOG.md, add an entry in the format already there — match it exactly rather than importing Keep a Changelog into a repo that doesn't use it. New section at the top, version and ISO date, grouped by Added / Changed / Fixed / Removed.

Write entries for the user of the package, from the diff, not from commit subjects. "Bump deps" is not an entry; "requires Node 20" is. Breaking changes get their own callout with the migration step.

No changelog in the repo? Don't create one uninvited — mention it as an option.

5. Verify, then tag

Run the test suite before tagging. A pushed tag is effectively permanent; a broken one gets re-cut as a new version, never moved.

git commit -am "chore(release): v1.2.0"     # or the repo's existing convention
git tag -a v1.2.0 -m "v1.2.0"

Match the repo's existing tag style — check git tag --list | tail. Common forms are v1.2.0, bare 1.2.0, and package@1.2.0 in monorepos. Go requires the v. Claude Code plugins use claude plugin tag, which writes {name}--v{version} and checks that plugin.json and the marketplace entry agree. It tags HEAD, so every other version file — a .codex-plugin/plugin.json included — must already be in the release commit. Without the claude CLI (in Codex, say), check that agreement yourself and create the same {name}--v{version} tag with git tag -a.

6. Push

Push the release commit and the tag — in a sandbox without network (Codex's default), with network access approved:

git push origin HEAD
git push origin v1.2.0        # or: git push --follow-tags

Never --force, and never move a tag that is already on the remote — a version someone may have installed does not get redefined. If the tag exists, cut the next version.

Pushing a tag often triggers release CI that builds and publishes. Say so in the report so the user knows what the push set in motion.

Publishing directly to a registry is a separate ask: no npm publish, cargo publish, twine upload, or gh release create unless the user requests it by name.

Report the new version, the files changed, the tag, the commit SHA, and where it was pushed.

If the working tree was dirty with unrelated work when you started, say so and stop before committing — a release commit that sweeps in someone's half-finished change is worse than a delayed release.