Changelog

Entries are typed. A change is written as TypeScript, so the compiler

insists that a breaking change names the exports it breaks and says how to migrate. The entries that cost somebody an afternoon are the ones that cannot be filed empty.

The release gate checks them against the package. Before a release goes

out, the exports that vanished or changed shape are compared with the exports the entries name. Forget an entry and the release stops. Nobody has to remember.

Migrations are data. A rename and a move are the overwhelming majority

of real breaking changes, and both are mechanical. Written as data they can be applied — by a CLI, an editor, or a hosted upgrade button — without running a line of code that came from a registry.

Checked where you type it

An entry can be written against the package's own API, and add scaffolds it that way when it finds one:

Suggested rather than required, for two reasons: a removed entry names something that has just stopped existing, and typeof Api cannot see type-only exports at all. The gate is the certain half — it reads the published .d.ts, which carries them.

The kinds

breaking and removed cost a consumer work, and the type refuses them without symbols and a migration. added, changed, deprecated, fixed, security and internal do not.

The migrations

Shape — What it means — Applied

rename: { from, to } — An export kept its meaning and changed its name — yes

moved: { symbol, from, to } — An export moved to another entry point — yes

resubpath: { from, to } — A whole entry point moved — yes

the version in package.json and the newest release agree;

package.json still ships both documents, and nothing is sitting in the

entry directory that no release will read;

the entries name every export that moved since the newest published

version — not the one in package.json, which between release and publish is a version nobody can fetch;

and every migration describes what actually happened: a rename whose

destination this version does not export, a rename whose source is still exported, a move to an entry point the package does not have, a removal of something still there.

That last one is what makes an applicable migration safe to apply. A migration that reads correctly and rewrites working code into something that does not compile is the whole risk of automating an upgrade, and it fails the release instead.

--offline skips the two that talk to the registry.

adopt also writes prepublishOnly, so the gate runs however a publish was started — a release script, a bare npm publish, a CI job. A rule that can be walked around eventually is.