| name | add-changeset |
| description | Add a changeset to the current change. Use when preparing a PR that affects published packages, when asked to 'add a changeset', or when CI reports a missing changeset. Detects monorepos and selects affected packages automatically. |
Add Changeset
A changeset declares which packages are affected by a change, the semver bump type, and a user-facing summary. It lives as a markdown file in .changeset/ and is consumed automatically by CI to version and publish packages.
When to Add One
Add a changeset when the change:
- Fixes a bug in a published package (
patch)
- Adds a new feature or public API (
minor)
- Breaks an existing API or removes something (
major)
- Updates a dependency in a way users need to know about (
patch)
Skip — use --empty instead — when:
- CI requires a changeset file but the change is
ci:, chore:, test:, or internal refactor with no API/behavior change
- The only changed files are in
examples/, docs/, or non-published packages (check private: true and "ignore" in .changeset/config.json)
--empty means: "I acknowledge no packages need versioning for this change."
Steps
1. Detect the setup
ls .changeset/config.json
Read .changeset/config.json to find:
"fixed" — packages that share the exact same version; bumping one bumps all"linked" — packages that share the highest bump type but keep independent versions"ignore" — packages excluded from versioning"access" — "public" means scoped packages publish publicly
2. Detect the package manager
| Lockfile present | Manager |
|---|
pnpm-lock.yaml | pnpm |
bun.lock / bun.lockb | bun |
yarn.lock | yarn |
package-lock.json | npm |
3. Identify affected packages (monorepo)
In a monorepo (has pnpm-workspace.yaml, workspaces in root package.json, or bun.workspace.ts):
git diff --name-only origin/main...HEAD
Map changed files to their owning package (find nearest package.json above each changed file). Apply fixed group rules: if any package in a fixed group is affected, all are.
In a single-package repo, the root package is always the affected package.
4. Determine bump type
| Change type | Bump |
|---|
| Removes or renames public API, breaks existing usage | major |
| Adds new exported function, class, option, or command | minor |
| Bug fix, internal refactor, dependency update | patch |
When unsure between minor and patch, ask the user.
5. Run the command
pnpm cs
pnpm changeset
bun run changeset
npx changeset
For --empty:
pnpm changeset --empty
The interactive prompt asks you to select packages (space to select, enter to confirm) and choose a bump type. Write the summary there.
6. Write a good summary
The summary appears verbatim in CHANGELOG.md. Rules:
- Imperative mood: "Add support for X" not "Added support for X"
- User-facing: describe the effect, not the implementation
- One line is enough; add bullet points only for breaking changes that need migration steps
- No references to internal file names or commit SHAs
Good: Add retry option to fetch client
Bad: Updated fetchClient.ts to handle retries in the error handler
7. Commit the changeset
git add .changeset/
git commit -m "chore: add changeset"
What Happens Next (don't intervene)
Once the changeset is merged to the base branch, the CI release workflow (changesets/action) will automatically:
- Open or update a "Version Packages" PR that bumps
package.json versions and updates CHANGELOG.md
- When that PR is merged, publish to npm and create GitHub releases
Never manually edit CHANGELOG.md — it is fully generated by changeset version. Never add changesets to a "Version Packages" PR — it will be overwritten.
Verification
npx changeset status
npx changeset status --since=main
