Changesets

In a repo that releases through changesets, a changeset is part of finishing the work, not a step somebody has to ask for. Check for a .changeset/ folder; without one, this skill does not apply.

What gets one

A changeset describes what changed against the release branch (usually main), not against the last commit.

A branch often adds something and then corrects it a few commits later. Nobody reading CHANGELOG.md ever saw the broken version, so the correction gets no changeset of its own. Amend the feature's changeset instead if it now says something untrue.

The test is one question: did the behavior being fixed ever reach a release? A fix for something users have today, or anything the release branch does not have at all, gets a changeset.

Changes users never see get none: tests, internal tooling, CI, docs that do not ship with the package. That includes everything under docs/ (roadmaps, debates, proposals, decisions). When unsure, ask whether the entry would mean anything to someone reading the changelog.

The bump level

The question is not how big the change looks. It is whether the thing existed before.

• patch: something that already existed now behaves differently. A bug fix, a retuned number, a rewritten internal path, a relaid screen, a performance win. All of these are patch, however different the result looks.
• minor: something exists that did not exist before. A new export, option, command, screen, event or field callers can set. If a user could not reach it yesterday and can today, it is minor.
• major: ask first. Never write one on your own judgment. Say what you think warrants it (a removed export, a changed signature, a changed default that breaks callers) and let the maintainer decide.

One change often does both: adding a new option is minor, retuning an existing default is patch. When one changeset covers both, take the higher level.

Packages before 1.0 often treat minor as breaking. Follow the repo's .changeset/config.json and its history; when the two rules conflict, ask.

The file

A markdown file in .changeset/, named in kebab-case as a short sentence about the change, not a ticket or a component: empty-carts-total-zero.md, tax-rounds-half-up.md.

---
'<package-name>': patch
---

One line saying what is true now.

Take the package name from the name field of the package's package.json. In a monorepo, list every package whose published behavior changed, each with its own level, and nothing else.

The prose

• One line for one change. A changeset is a changelog entry: it says what is true now and stops. Leave out the reasoning, the trade-offs and what it replaced.

• Several changes: a list, one line each.

  ---
  'cart': patch
  ---
  
  - Subtotals include the first item in the cart.
  - Discounts round half up instead of losing a cent on some totals.

• Write for someone reading CHANGELOG.md, not the diff. Name the behavior, not the file or the function.
• Follow the plain-writing rules if that skill is installed: no em-dashes, plain sentences, no build-up. Wrap like the files already there.
• When a change alters data or output that existing users already have (a saved format, generated content, a migration), say so on its own line.

Before concluding one is missing

The release step folds every changeset into CHANGELOG.md and empties .changeset/, so a folder holding only README.md and config.json does not mean work went unrecorded. Check CHANGELOG.md before writing a second entry for something already released.

Held for a later release

Every changeset on the release branch ships with the next release. A pull request can be held for a later release, by a roadmap fence or by the maintainer. Keep its changeset in the pull request and hold the merge. Do not remove the changeset to slip the code into the current release, because the change would then ship with no changelog entry.

In reviews

When reviewing a pull request in such a repo, check that it has a changeset when it should, that the level follows the rules above, and that a major was approved. A missing or wrong changeset is a should-fix finding, not a blocking one.