release-management

Release Management

Releasing turns committed work into a versioned, consumable artifact — a tag, a package, an image — with a truthful version number and a record of what changed. It is not deploying (that's deployment-checklist): a release can exist without a deploy, and vice versa.

⛔ The Iron Law

Never publish without a fresh verification gate — and never impose more release process than the project warrants.

Registry publishes are effectively irreversible: a version number, once published, is burned even if you yank it, and whatever shipped inside it is already on users' machines. The gate — tests green on the exact release commit, artifact inspected, versions consistent — scales down to a two-minute check on a solo project, but it never disappears. Ceremony scales with the project; the gate doesn't.

Scope boundary: "is it safe to ship?" is not a release question

Deploy safety — migrations, downtime, rollback readiness, whether today is the day — belongs to deployment-checklist, with rollback-strategy for the reversal plan. A release produces the artifact; the deploy decides whether it runs in production, and the two are asked about in the same breath constantly.

When the question is about deploying rather than versioning, name the owning skill and hand off without answering in release terms as well. Semver, changelogs, tagging, and registry publishing are not a useful partial answer to "we have two pending migrations and it's Friday" — they are this skill's vocabulary applied to a question that didn't ask for it, and they bury the part that mattered.

Step 1: Detect Existing Conventions — Never Assume Greenfield

Before proposing anything, find what the project already does:

• Release config: .changeset/, release-please-config.json, .releaserc* / release key in package.json, cliff.toml, .goreleaser.yml
• Docs: RELEASING.md, release sections in CONTRIBUTING.md
• CI: publish/release jobs in workflow files (tag triggers, npm publish, twine upload)
• History: git tag --list (scheme and cadence), CHANGELOG.md format, commit-message style

If conventions exist, follow them for this release; propose improvements as a separate change. An org's release process usually encodes constraints you can't see from the repo.

Step 2: Right-Size the Process

Tier	Signals	Process
Solo / personal	One maintainer, few users, irregular cadence	Manual: bump version, changelog entry (or gh release create --generate-notes), annotated tag, GitHub release. No automation tooling.
Team / published package	Multiple contributors, external consumers, regular cadence	Conventional commits feeding one automation tool (release-please / changesets / semantic-release), generated changelog, publish gate as a CI stage
Org / platform / monorepo	Many packages, coordinated versions, compliance needs	Release PRs, protected release branches, provenance / trusted publishing, pre-release channels, coordinated monorepo versioning

Under-processing breaks consumers; over-processing kills a small project's momentum. State which tier applies and why. Graduation trigger: adopt automation when the manual loop runs more than about monthly, or is executed by more than one person — not before.

The table is how you choose, not what you deliver. Name the tier, then work in that tier only. Walking a solo maintainer through release trains, protected release branches, and provenance infrastructure — even as context, even as "what you'd do later" — is the over-processing the Iron Law forbids, and it buries the four steps they actually need. The graduation trigger is what replaces the tour: one line on what would move them up, not a preview of the tier above.

Step 3: Decide the Version

• Something with consumers of a versioned contract (library, CLI, API) → SemVer: breaking → MAJOR, feature → MINOR, fix → PATCH. Pre-1.0, MINOR is the breaking-change lever — and don't promise 1.0 stability until you mean it.
• A deployed app or service nobody installs by version → CalVer or a build number is fine; don't cargo-cult SemVer where there is no consumer contract.
• The version lives in one source of truth; every other occurrence (manifests, generated files) is stamped from it. Grep for the old version before tagging — drift here is the classic broken release.
• Never inflate ("bump minor to be safe"): the version is communication to consumers, not marketing. Inflating it lies about compatibility.

Step 4: Prepare the Release

• Changelog from commits, in Keep a Changelog form. Conventional commits map mechanically: feat → Added, fix → Fixed, behavior change → Changed, feat! / BREAKING CHANGE: → MAJOR.
• Release notes ≠ changelog: notes lead with highlights and breaking changes plus their upgrade steps — what a consumer must know before upgrading, not a commit list.
• Bump the source-of-truth version, regenerate anything stamped from it, and settle the changelog — promote [Unreleased] if the file is hand-maintained; if a tool generates it, don't hand-curate alongside (a generated changelog plus a hand-written [Unreleased] is how the two silently diverge — the tool prepends and never folds). There, fix the commit subject, not the file.

Step 5: Gate, Then Publish

Run the gate on the exact commit being released (including the version-bump commit):

1. Clean working tree, correct branch — git status.
2. Tests and build green on this commit, not "they passed yesterday on main".
3. Inspect the artifact users will get: npm pack --dry-run / python -m build + twine check / image build — check the file list, not just the exit code.
4. Version consistency: manifest(s), changelog heading, and the tag you're about to create all agree.

Then, in order: annotated tag (vX.Y.Z) → publish → post-publish smoke test (install the published artifact in a clean directory and exercise it) → GitHub release with the notes. If the smoke test fails, the fix is a new patch version — which is exactly why the gate runs first.

Step 6: Automate What Repeats (Tier 2+)

Pick one tool — they solve the same problem and fight each other:

• release-please — release PRs that accumulate changes; GitHub-centric; good monorepo support; a human merge is the final gate.
• changesets — contributors declare intent per change; the standard for JS/TS monorepos with independent package versions.
• semantic-release — fully automated publish on merge; no human gate, so the CI gate must be airtight.

Selection detail, trusted publishing/provenance, pre-release channels and dist-tags, monorepo fixed-vs-independent versioning, and hotfix/backport flows: references/release-tooling.md.

Rationalizations to Reject

Excuse	Reality
"It's a one-line fix — publish now, run tests after"	Published versions can't be overwritten. Start the tests, prep in parallel, publish when green; if consumers truly can't wait, publish to a next dist-tag, not latest.
"Small project — tags and changelogs are overkill"	The lightweight tier costs minutes and buys bisect, rollback, and consumer trust. Skipping versioning is not right-sizing.
"Let's set up semantic-release" (solo repo, three releases a year)	Below regular cadence, automation costs more than it saves. Right-sizing cuts both ways.
"Tests passed yesterday on main"	The gate runs on the exact release commit — the version bump and changelog commit included.
"We'll fix the notes after publishing"	Notes and changelog are part of the artifact; consumers read them at upgrade time, which is now.
"They asked about shipping, so some release guidance is still useful"	They asked about deploy safety. Versioning advice alongside it reads as the answer and displaces the migration and rollback questions that actually decide it. Hand off and stop.

Red Flags — Stop and Correct Course

• Publishing from a dirty tree, an unpushed branch, or a commit CI never saw.
• The manifest, the tag, and the changelog disagree on the version.
• Two release-automation tools active in the same repo.
• "Misc fixes and improvements" as the entire changelog entry for a consumer-facing release.
• A release procedure that requires hand-editing generated files.

Cross-Skill References

• git-workflow — the conventional commits that feed automated bumps
• cicd-pipeline — implementing the publish gate as a pipeline stage
• deployment-checklist / rollback-strategy — deploying the released artifact safely
• project-documentation — changelog upkeep between releases
• verification-before-completion — the evidence discipline the gate is built on