| name | release-and-changesets |
| description | Use when adding a changeset to a PR, deciding whether a PR needs one, cutting or debugging a release, or when the Version PR / npm publish flow looks wrong. |
Changesets and releases in the Nextly monorepo
The changeset rules (non-negotiable)
- ONE changeset per PR, not per commit.
- It must list ALL published packages (they are a
fixed lockstep group
in .changeset/config.json; the repo is in pre-release alpha mode via
.changeset/pre.json).
- Always
patch while in alpha.
- The description is the USER-facing impact, one or two lines, not an
implementation note.
- No changeset for PRs that touch only tests, CI/workflows, repo docs,
or other non-published files. When in doubt: does the change alter what a
user installs from npm? No -> no changeset.
Create one with pnpm changeset (select all packages, patch) or write the
file by hand under .changeset/ following an existing one.
How releasing actually works (CI-only)
- PRs with changesets merge to
main.
- The Changesets bot maintains a Version PR ("chore: version packages
(alpha)") that accumulates pending changesets, bumps every package in
lockstep, and updates changelogs.
- Merging the Version PR publishes: the release workflow builds and
publishes all packages to npm via trusted publishing (OIDC) in the
protected environment. There are no local publishes; never run
changeset publish or npm publish yourself.
- Tags (
vX.Y.Z-alpha.N) and a consolidated GitHub Release are created by
the workflow.
Known gotchas (learned the hard way)
- The release workflow pins an exact npm version on purpose (a floating
npm@latest once broke every release via an engines bump). Do not
"simplify" it back to latest.
- Old branches can restore already-published changeset files on merge; if
the Version PR suddenly lists ancient entries, check for resurrected
.changeset/*.md files and delete them in a cleanup PR.
- The npm
latest dist-tag for the unscoped packages is managed manually
after publishes; a publish alone does not move it.
- If the Version PR looks wrong, fix the inputs (changeset files on main);
never edit the Version PR's generated diff by hand.
