Release and Changelog
Overview
A workflow for cutting a clean release: bump the version, write changelog
entries that reflect the actual diff, tag, publish. The skill exists because
the most common release-time failure isn't the publishing mechanism — it's the
changelog that says "various improvements" or "performance enhancements"
without naming what changed. Users reading the notes can't decide whether to
upgrade; engineers debugging six months later can't bisect on the release.
This skill enforces that the changelog is built from the diff, not from a
remembered list of features. Used after code-review-loop and before
publishing/tagging.
When to Use
- Cutting a numbered release (
v1.2.0, v2.0.0-rc1, etc.)
- Updating a
CHANGELOG.md after a feature merge in projects with a
rolling-changelog policy
- Bumping a package version in a published library
- Writing release notes for a deploy that crosses a version boundary
When NOT to Use
- Continuous-deployment projects with no version concept (every merge is a
deploy; there's no release event)
- Internal services where deploys don't carry version semantics for consumers
- A trivial doc-only or test-only change (changelog entry optional per
project policy)
Process
Step 1: Determine the version bump
Goal: Pick the correct SemVer level.
Inputs: The set of changes since the last release.
Actions:
- List every change since the last tag:
git log <last-tag>..HEAD --oneline.
- Classify each change:
- Breaking (incompatible API change, removed feature, changed behavior
that callers depend on) → MAJOR bump
- New feature (additive, backward-compatible) → MINOR bump
- Bug fix or internal improvement (no behavioral change for callers) →
PATCH bump
- The bump is the highest classification across all changes. One breaking
change in a release of 50 fixes is still a MAJOR bump.
- If the project is pre-1.0 (
0.x.y), treat MINOR as breaking-allowed and
PATCH as the conservative bump. The 0.x.y SemVer license to break is real
but should still be exercised consciously.
Output: The new version number, with the rationale: v1.2.0 → v1.3.0 (MINOR: added X feature, no breaking changes).
Step 2: Build the changelog from the diff
Goal: A CHANGELOG.md entry built from actual changes, not memory.
Inputs: The change list from Step 1.
Actions:
- Open
CHANGELOG.md. If it doesn't exist, create one following Keep a
Changelog (keepachangelog.com) format.
- Add a section at the top:
## [<version>] - <YYYY-MM-DD>.
- Below it, add subheadings as needed:
### Added (new features)### Changed (changes to existing functionality)### Deprecated (features marked for removal)### Removed (deleted features)### Fixed (bug fixes)### Security (vulnerability fixes)
- For each change in your Step 1 list, write one entry under the right
subheading. Each entry:
- Names what changed in user-observable terms (not implementation terms).
- Cites the PR or commit hash.
- Names the consumer impact if non-trivial (migration step, removed feature,
etc.).
- Reflect the actual diff. If you wrote "Improved performance" without
naming what was improved, return to the diff and find the specific
improvement.
Output: A CHANGELOG.md entry that reads like the diff, not like marketing
copy.
Step 3: Update the manifest
Goal: Bump the version where the package's tools look for it.
Inputs: The new version number from Step 1.
Actions:
- Update the version in every manifest the project uses:
package.json (Node)pyproject.toml / setup.py (Python)Cargo.toml (Rust)plugin.json / marketplace.json (Claude Code plugin)VERSION file (where applicable)
- If the project has a generated build artifact embedding the version
(
__version__ constant, build banner), regenerate it.
- Confirm all manifests show the same version. Drift here is a common bug.
Output: All version manifests aligned to the new version.
Step 4: Atomic release commit
Goal: One commit that captures the release.
Inputs: Updated manifests + updated CHANGELOG.
Actions:
- Stage the manifest changes and the CHANGELOG entry.
- Commit with a message that names the version and the level:
Release v1.3.0 (MINOR) or follow project convention.
- The commit should contain only the version bump and the changelog. No
feature changes, no fixes, no "while I was here" cleanups. Atomic.
Output: A single release commit on the release branch (or main, depending
on the project's branching model).
Step 5: Tag and publish
Goal: Make the release discoverable to consumers.
Inputs: The release commit.
Actions:
- Tag the commit:
git tag -a v1.3.0 -m "v1.3.0 (MINOR): added X feature".
- Push the tag:
git push origin v1.3.0.
- If the project publishes to a registry (npm, PyPI, crates.io, marketplace),
run the publish command. Verify the published artifact matches the tag.
- If a release notes mechanism exists (GitHub Releases, etc.), copy the
CHANGELOG entry to it. Don't paraphrase; the changelog and the release notes
should match.
- If there's a deploy associated with the release, trigger it now (or follow
the project's deploy procedure).
Output: Tagged, published release. Tag matches the version; published
artifact matches the tag.
Step 6: Post-release verification
Goal: Confirm consumers can actually consume the release.
Inputs: A published release.
Actions:
- Install the released artifact in a clean environment (a fresh container,
a separate venv, a sandboxed install). Don't test from your dev box.
- Run a smoke check: import the package, run a hello-world, hit the new
feature.
- If the install fails or the smoke check breaks, the release is wrong even
though it's tagged. Yank/unpublish if the registry supports it; otherwise
ship a patch release.
Output: A confirmation that the release works for a fresh consumer.
Rationalizations
| Excuse |
Why it sounds reasonable |
Why it's wrong |
What to do instead |
| "It's just a patch — I don't need to write changelog entries for every fix." |
Patch releases are routine. Per-fix entries can feel like ceremony. |
The changelog is a contract with consumers. A patch with no entries reads as "no notable changes" — but the consumer who runs npm update and gets a regression has no way to bisect on the release notes because the notes are empty. The 60 seconds of writing the entry buys hours of debuggability later. |
Write one entry per fix. Even one line ("Fixed off-by-one in pagination — #234"). The cost is small; the value is durable. |
| "The diff is small — I can write the changelog from memory." |
A small diff really is reconstructable from memory. |
Memory drifts in even short timescales. The PR you wrote yesterday already has details (the exact behavior change, the constraint you handled) that aren't in your head today. The changelog written from memory says "improved X" instead of "X now respects Y under condition Z," which is the actual content the consumer needs. |
Build the changelog from git log <last-tag>..HEAD. Even for small diffs. The 30 seconds of running the command and reading the commits is the discipline. |
| "Nobody reads changelogs anyway." |
Some consumers really don't read changelogs. Auto-update bots upgrade silently. |
"Nobody reads them" is true until someone debugs a regression and bisects on releases. The changelog is the bisect index. The empty changelog turns "which release introduced this?" into a manual diff comparison; the populated changelog turns it into a 30-second read. |
Write the changelog for the future debugger, not for the casual reader. The audience is the engineer six months from now who needs to know what changed in v1.3.0. |
| "I'll bump the version after I publish — the registry will tell me what to use." |
Some registries do auto-increment. Letting the tool decide feels efficient. |
Auto-increment doesn't know your SemVer intent. A breaking change auto-bumped as PATCH ships under a version consumers will pick up by default — they get the breaking change without warning. The version is your communication; only you know what the changes mean. |
Bump the version before publishing. Step 1 → Step 3 in this skill. The version reflects intent, not just sequence. |
| "I'll skip the post-release smoke check — CI tested everything." |
CI does run the test suite. |
CI tests the source tree, not the published artifact. A package that builds and tests fine in CI may publish broken because of a missing file in the package manifest, an unset environment variable in the publish step, or a registry-specific transformation that broke something. The smoke check on a fresh install catches the published-vs-source gap. |
Run the smoke check (Step 6). Fresh container, install from registry, run the basic flow. 5 minutes; it catches the class of bugs CI cannot. |
| "I'll batch multiple unrelated fixes into one release commit." |
Fewer commits is cleaner. |
The release commit is the bisect target; a clean release commit (only the bump and changelog) is bisect-friendly. Mixing fixes into the release commit ties the release to the unrelated fixes — git revert of the release commit reverts the fixes too. |
Land fixes in their own commits before the release. The release commit only contains the version bump and changelog. Atomic in Step 4 means atomic. |
Evidence Requirements
| Checkpoint |
Required artifact |
What "no evidence" looks like |
| End of Step 1 |
Version bump rationale: <old> → <new> (<level>: <reason>) |
"Bumping the version." |
| End of Step 2 |
Changelog entries built from git log output, not memory |
"Various improvements." |
| End of Step 3 |
All manifests show the same version |
"Updated package.json." |
| End of Step 4 |
An atomic release commit with only manifest + changelog changes |
A release commit that also includes feature fixes. |
| End of Step 5 |
Tag pushed; published artifact verified to match tag |
"Tagged it." |
| End of Step 6 |
Smoke check output from a fresh-install environment |
"I'll trust it." |
Red Flags
- The changelog entry for a release is "Various improvements and bug fixes."
Build it from the diff.
- A MAJOR-level change (breaking) is in a MINOR release. Either the change
isn't actually breaking or the release is mis-leveled.
- The release commit contains code changes other than version bump + changelog.
Re-do as atomic.
- Manifests disagree on the version. Pick one and align them all.
- The git tag doesn't match the published artifact's version. Yank or correct.
- The smoke check was skipped. The release is unverified.
- The CHANGELOG file was force-edited to remove an entry. Releases shouldn't be
rewritten retroactively.
References
- Tom Preston-Werner, Semantic Versioning 2.0.0 (semver.org, 2013) — the
canonical reference for MAJOR/MINOR/PATCH semantics. Step 1 operationalizes
the SemVer rules with explicit classification.
- Olivier Lacan & contributors, Keep a Changelog 1.1.0 (keepachangelog.com) —
the format used in Step 2's subheading structure (Added, Changed, Deprecated,
Removed, Fixed, Security).
1---2name: release-and-changelog3description: Use when cutting a release, bumping a version, or writing release notes. Activate for keywords like "release", "version bump", "changelog", "release notes", "tag", "publish", "ship a release", "v1.x", "v2.x". Enforces version hygiene: SemVer respect, changelog discipline, atomic commits, tagged release. Always reflect the actual diff in the changelog -- never write notes from memory or marketing copy.4---56# Release and Changelog78## Overview910A workflow for cutting a clean release: bump the version, write changelog11entries that reflect the actual diff, tag, publish. The skill exists because12the most common release-time failure isn't the publishing mechanism — it's the13changelog that says "various improvements" or "performance enhancements"14without naming what changed. Users reading the notes can't decide whether to15upgrade; engineers debugging six months later can't bisect on the release.16This skill enforces that the changelog is built from the diff, not from a17remembered list of features. Used after `code-review-loop` and before18publishing/tagging.1920## When to Use2122- Cutting a numbered release (`v1.2.0`, `v2.0.0-rc1`, etc.)23- Updating a `CHANGELOG.md` after a feature merge in projects with a24 rolling-changelog policy25- Bumping a package version in a published library26- Writing release notes for a deploy that crosses a version boundary2728## When NOT to Use2930- Continuous-deployment projects with no version concept (every merge is a31 deploy; there's no release event)32- Internal services where deploys don't carry version semantics for consumers33- A trivial doc-only or test-only change (changelog entry optional per34 project policy)3536## Process3738### Step 1: Determine the version bump3940**Goal:** Pick the correct SemVer level.4142**Inputs:** The set of changes since the last release.4344**Actions:**45461. List every change since the last tag: `git log <last-tag>..HEAD --oneline`.472. Classify each change:48 - **Breaking** (incompatible API change, removed feature, changed behavior49 that callers depend on) → MAJOR bump50 - **New feature** (additive, backward-compatible) → MINOR bump51 - **Bug fix or internal improvement** (no behavioral change for callers) →52 PATCH bump533. The bump is the **highest** classification across all changes. One breaking54 change in a release of 50 fixes is still a MAJOR bump.554. If the project is pre-1.0 (`0.x.y`), treat MINOR as breaking-allowed and56 PATCH as the conservative bump. The 0.x.y SemVer license to break is real57 but should still be exercised consciously.5859**Output:** The new version number, with the rationale: `v1.2.0 → v1.3.060(MINOR: added X feature, no breaking changes)`.6162### Step 2: Build the changelog from the diff6364**Goal:** A `CHANGELOG.md` entry built from actual changes, not memory.6566**Inputs:** The change list from Step 1.6768**Actions:**69701. Open `CHANGELOG.md`. If it doesn't exist, create one following Keep a71 Changelog (keepachangelog.com) format.722. Add a section at the top: `## [<version>] - <YYYY-MM-DD>`.733. Below it, add subheadings as needed:74 - `### Added` (new features)75 - `### Changed` (changes to existing functionality)76 - `### Deprecated` (features marked for removal)77 - `### Removed` (deleted features)78 - `### Fixed` (bug fixes)79 - `### Security` (vulnerability fixes)804. For each change in your Step 1 list, write one entry under the right81 subheading. Each entry:82 - Names what changed in user-observable terms (not implementation terms).83 - Cites the PR or commit hash.84 - Names the consumer impact if non-trivial (migration step, removed feature,85 etc.).865. **Reflect the actual diff.** If you wrote "Improved performance" without87 naming what was improved, return to the diff and find the specific88 improvement.8990**Output:** A `CHANGELOG.md` entry that reads like the diff, not like marketing91copy.9293### Step 3: Update the manifest9495**Goal:** Bump the version where the package's tools look for it.9697**Inputs:** The new version number from Step 1.9899**Actions:**1001011. Update the version in every manifest the project uses:102 - `package.json` (Node)103 - `pyproject.toml` / `setup.py` (Python)104 - `Cargo.toml` (Rust)105 - `plugin.json` / `marketplace.json` (Claude Code plugin)106 - `VERSION` file (where applicable)1072. If the project has a generated build artifact embedding the version108 (`__version__` constant, build banner), regenerate it.1093. Confirm all manifests show the same version. Drift here is a common bug.110111**Output:** All version manifests aligned to the new version.112113### Step 4: Atomic release commit114115**Goal:** One commit that captures the release.116117**Inputs:** Updated manifests + updated CHANGELOG.118119**Actions:**1201211. Stage the manifest changes and the CHANGELOG entry.1222. Commit with a message that names the version and the level:123 `Release v1.3.0 (MINOR)` or follow project convention.1243. The commit should contain *only* the version bump and the changelog. No125 feature changes, no fixes, no "while I was here" cleanups. Atomic.126127**Output:** A single release commit on the release branch (or main, depending128on the project's branching model).129130### Step 5: Tag and publish131132**Goal:** Make the release discoverable to consumers.133134**Inputs:** The release commit.135136**Actions:**1371381. Tag the commit: `git tag -a v1.3.0 -m "v1.3.0 (MINOR): added X feature"`.1392. Push the tag: `git push origin v1.3.0`.1403. If the project publishes to a registry (npm, PyPI, crates.io, marketplace),141 run the publish command. Verify the published artifact matches the tag.1424. If a release notes mechanism exists (GitHub Releases, etc.), copy the143 CHANGELOG entry to it. Don't paraphrase; the changelog and the release notes144 should match.1455. If there's a deploy associated with the release, trigger it now (or follow146 the project's deploy procedure).147148**Output:** Tagged, published release. Tag matches the version; published149artifact matches the tag.150151### Step 6: Post-release verification152153**Goal:** Confirm consumers can actually consume the release.154155**Inputs:** A published release.156157**Actions:**1581591. Install the released artifact in a clean environment (a fresh container,160 a separate venv, a sandboxed install). Don't test from your dev box.1612. Run a smoke check: import the package, run a hello-world, hit the new162 feature.1633. If the install fails or the smoke check breaks, the release is wrong even164 though it's tagged. Yank/unpublish if the registry supports it; otherwise165 ship a patch release.166167**Output:** A confirmation that the release works for a fresh consumer.168169## Rationalizations170171| Excuse | Why it sounds reasonable | Why it's wrong | What to do instead |172|---|---|---|---|173| "It's just a patch — I don't need to write changelog entries for every fix." | Patch releases are routine. Per-fix entries can feel like ceremony. | The changelog is a contract with consumers. A patch with no entries reads as "no notable changes" — but the consumer who runs `npm update` and gets a regression has no way to bisect on the release notes because the notes are empty. The 60 seconds of writing the entry buys hours of debuggability later. | Write one entry per fix. Even one line ("Fixed off-by-one in pagination — #234"). The cost is small; the value is durable. |174| "The diff is small — I can write the changelog from memory." | A small diff really is reconstructable from memory. | Memory drifts in even short timescales. The PR you wrote yesterday already has details (the exact behavior change, the constraint you handled) that aren't in your head today. The changelog written from memory says "improved X" instead of "X now respects Y under condition Z," which is the actual content the consumer needs. | Build the changelog from `git log <last-tag>..HEAD`. Even for small diffs. The 30 seconds of running the command and reading the commits is the discipline. |175| "Nobody reads changelogs anyway." | Some consumers really don't read changelogs. Auto-update bots upgrade silently. | "Nobody reads them" is true until someone debugs a regression and bisects on releases. The changelog is the bisect index. The empty changelog turns "which release introduced this?" into a manual diff comparison; the populated changelog turns it into a 30-second read. | Write the changelog for the future debugger, not for the casual reader. The audience is the engineer six months from now who needs to know what changed in v1.3.0. |176| "I'll bump the version after I publish — the registry will tell me what to use." | Some registries do auto-increment. Letting the tool decide feels efficient. | Auto-increment doesn't know your SemVer intent. A breaking change auto-bumped as PATCH ships under a version consumers will pick up by default — they get the breaking change without warning. The version is your communication; only you know what the changes mean. | Bump the version *before* publishing. Step 1 → Step 3 in this skill. The version reflects intent, not just sequence. |177| "I'll skip the post-release smoke check — CI tested everything." | CI does run the test suite. | CI tests the source tree, not the published artifact. A package that builds and tests fine in CI may publish broken because of a missing file in the package manifest, an unset environment variable in the publish step, or a registry-specific transformation that broke something. The smoke check on a fresh install catches the published-vs-source gap. | Run the smoke check (Step 6). Fresh container, install from registry, run the basic flow. 5 minutes; it catches the class of bugs CI cannot. |178| "I'll batch multiple unrelated fixes into one release commit." | Fewer commits is cleaner. | The release commit is the bisect target; a clean release commit (only the bump and changelog) is bisect-friendly. Mixing fixes into the release commit ties the release to the unrelated fixes — `git revert` of the release commit reverts the fixes too. | Land fixes in their own commits before the release. The release commit only contains the version bump and changelog. Atomic in Step 4 means atomic. |179180## Evidence Requirements181182| Checkpoint | Required artifact | What "no evidence" looks like |183|---|---|---|184| End of Step 1 | Version bump rationale: `<old> → <new> (<level>: <reason>)` | "Bumping the version." |185| End of Step 2 | Changelog entries built from `git log` output, not memory | "Various improvements." |186| End of Step 3 | All manifests show the same version | "Updated package.json." |187| End of Step 4 | An atomic release commit with only manifest + changelog changes | A release commit that also includes feature fixes. |188| End of Step 5 | Tag pushed; published artifact verified to match tag | "Tagged it." |189| End of Step 6 | Smoke check output from a fresh-install environment | "I'll trust it." |190191## Red Flags192193- The changelog entry for a release is "Various improvements and bug fixes."194 Build it from the diff.195- A MAJOR-level change (breaking) is in a MINOR release. Either the change196 isn't actually breaking or the release is mis-leveled.197- The release commit contains code changes other than version bump + changelog.198 Re-do as atomic.199- Manifests disagree on the version. Pick one and align them all.200- The git tag doesn't match the published artifact's version. Yank or correct.201- The smoke check was skipped. The release is unverified.202- The CHANGELOG file was force-edited to remove an entry. Releases shouldn't be203 rewritten retroactively.204205## References206207- Tom Preston-Werner, *Semantic Versioning 2.0.0* (semver.org, 2013) — the208 canonical reference for MAJOR/MINOR/PATCH semantics. Step 1 operationalizes209 the SemVer rules with explicit classification.210- Olivier Lacan & contributors, *Keep a Changelog 1.1.0* (keepachangelog.com) —211 the format used in Step 2's subheading structure (Added, Changed, Deprecated,212 Removed, Fixed, Security).
duthaho