Release Notes

Release notes

A release page is read by pnpm users, most of them skimming for the one entry that affects them. It is not a log of the pull requests that landed. Every entry has to earn its line.

The wording rules for a single entry live in the "Changeset style" section of CLAUDE.md. This skill is about the set: which entries exist at all, how they are grouped, what order they appear in, and how the page reads end to end.

Edit the composed section, not the intents

1. Each merged pull request leaves a .changeset/<id>.md intent: a frontmatter map of package to bump type, then the prose.
2. pnpm run bump on the release branch consumes the pending intents, deletes them, and composes them into .changeset/changelogs/<package>@<version>.md, one section per released package, grouped into Major, Minor, and Patch changes.
3. That file is the release page. The Rust CLI's GitHub release body is literally tail -n +2 .changeset/changelogs/pacquet@<version>.md plus the sponsors fragment (.github/workflows/release.yml), and the same section is composed into the published CHANGELOG.md. For a stable v11 or v12 release, it also becomes the pnpm.io release page (DOCUMENTATION.md).

So curate .changeset/changelogs/<package>@<version>.md directly, on the release PR branch, after the bump has written it. The intents are gone by then, so the composed section is the only surviving copy - there is nothing to keep in sync. Editing it is also the only way to reorder or merge entries: the composer emits them in alphabetical order of the intent filename and offers no other lever.

Two things this does not cover:

• Bump types still live in the intents. If the planned version is wrong, fix the intent's frontmatter and re-run the bump. That is the only reason to touch an intent at this stage.
• A published version's section is frozen. confirmed_published_versions garbage collects a parked section only when the published changelog contains it verbatim, so editing one after release breaks the match forever. Before publish, it is the right place to edit; after, corrections go in a new changeset.

Curation lives on release-pr/<target>, which the Create Release PR workflow rebuilds from the target branch on every dispatch. A re-dispatch discards it. Curate when the release is actually going out.

What to cut

Defects introduced and fixed between two releases. If the bug never existed in a published version, no user can recognise it, and the entry only advertises that the feature arrived broken. To decide, find the release commit for the package's previous version (git log --grep 'chore(release)') and check whether the code the fix touches predates it. A follow-up to a feature shipping in this same release is the usual case.

Internals with no observable consequence. Refactors, renamed modules, "now uses X internally". If you cannot finish the sentence "so you can ..." or "so it no longer ...", drop it.

Mechanism the reader will not act on. Keep the sentence that names the command, setting, or symptom. Cut the one explaining which cache, tier, or syscall changed, unless the reader has to configure around it.

What to merge

Merge entries that describe one change as the user experiences it, even when they came from different pull requests:

• Same command or setting, same defect (two pnpm dedupe selection bugs).
• One symptom with several causes (install failing on Android for a TLS reason and a permissions reason).
• A feature and the follow-ups that completed it (a container registry plus its size limits, token scopes, and blob deletion).
• A cluster of speedups with one headline (Sped up repeat installs. then the specifics).

Two entries that mention the same setting from different angles are duplication even when both are accurate. Say it once, in the entry the reader will find first.

Lead the page

Deno opens a release post with one sentence naming the top few changes: "Deno 1.28 ships with stabilized npm modules, auto-discovered lock file, a new subprocess API, and more." A reader decides from that line whether to read on.

Write that line as a paragraph directly under the ## <version> heading, before the first ### section. tail -n +2 keeps it, so it becomes the opening line of the GitHub release body, and it sits under the version heading in CHANGELOG.md. Name three or four things at most, in the words the entries below use.

Ordering

The published page has no headings other than Major, Minor, and Patch. Thirty patch bullets arrive as one undifferentiated list, so the order is the whole of the page's structure. Projects that categorise explicitly publish the ranking you want: Gitea orders BREAKING, SECURITY, FEATURES, PERFORMANCE, ENHANCEMENTS, API, BUGFIXES; uv splits Enhancements, Performance, Bug fixes, Preview features, Breaking changes. pnpm's composer emits no such headings, so build those blocks out of the order:

1. Breaking changes and anything the reader must act on.
2. Security fixes. Gitea puts these second for a reason; a reader who stops after two entries must not have missed one. Lead the section they fall in, and say in the lead paragraph that the release carries one.
3. Installs or commands that fail outright, and anything that damaged files.
4. Wrong results: a dependency resolved, linked, or skipped incorrectly.
5. Speed and resource use.
6. Behavior corrections in one command or setting.
7. Output: messages, warnings, help text.

The Major, Minor, and Patch headings cut across that ranking and you cannot reorder past them, so a security fix carrying a patch bump still lands below every feature. That is what the lead paragraph is for.

Within a section, group: all the speedups together, all the pnpm dedupe fixes together, the Windows items together. A reader who hits three consecutive entries about output messages knows the interesting part is over.

Past about a dozen entries in one section, name the groups. Add #### subject headings under the ### bump heading, ordered by the ranking above:

### Patch Changes

#### Installing packages

- ...

#### Resolving and linking dependencies

Aim for four to eight groups and at least two entries in each; a group of one is noise, so fold it into its neighbour. Name them for what the reader was doing when they hit the bug (Installing packages, Running scripts and tasks, Windows), not for the subsystem that changed. Leave a section of a dozen or fewer flat - the headings cost more than they save.

Both consumers tolerate the extra level: release.yml writes the Rust release body with tail -n +2, and getChangelogEntry (pnpm11/__utils__/get-release-text) slices between headings of the same depth as ## <version>, so a #### heading neither ends the slice nor is dropped. It does scan every heading for major|minor|patch, so avoid a group literally named "Patching" - call it "Patched dependencies".

In the Minor section of a feature release, lead with the three to five entries that change how people work, the way Playwright leads with a handful of highlights before its flat API list. Largest diff is not the same as most important. For the one or two biggest, TypeScript's shape is worth copying: open with the problem the reader recognises, then the new capability, then the code.