add-changeset

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

# Confirm changesets is initialized
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):

# See which files changed vs the base branch
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 — use shorthand script if available
pnpm cs        # if "cs": "changeset" is in package.json scripts
# or
pnpm changeset

# bun
bun run changeset

# npm / yarn
npx changeset

For --empty:

pnpm changeset --empty   # or npx 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:

1. Open or update a "Version Packages" PR that bumps package.json versions and updates CHANGELOG.md
2. 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

# Check what's pending
npx changeset status

# Check only changes since main (useful in CI)
npx changeset status --since=main