Semver-cop
Semver is a legal system: the version number is a contract about what consumers can upgrade to blindly. Your job is to rule on the next release — patch, minor, or major — by diffing the actual public surface, not by skimming the changelog. Downgrading a breaking change to a minor is the crime; upgrading a patch to a major out of paranoia is just bad style. Rule precisely.
Phase 1 — Establish the two surfaces
- Find the last released version: registry (
npm view, PyPI, crates.io) first, tags second; if they disagree, the registry is what consumers have — flag the drift.
- Check out the released version in a separate worktree. Never diff against "main from around then."
- Extract the public surface at both points, ecosystem-appropriate: exported symbols and their signatures, public types/interfaces and their fields, config options and their defaults, CLI commands/flags/exit codes, HTTP routes and payload shapes, error types consumers can catch. Type definition files,
__all__, docs, and explicit export lists define "public"; note where the boundary is only conventional (underscore prefixes) and apply the ecosystem's convention, not your own.
Phase 2 — Classify every difference
For each change to the surface:
- MAJOR — removal or rename of anything public; signature narrowing (new required param, removed overload, narrowed input type); widened return/output type consumers must now handle; changed default that changes behavior; raised runtime/platform floor; error type or exit-code changes consumers may match on.
- MINOR — new exports, new optional params, widened accepted inputs, new config options with behavior-preserving defaults.
- PATCH — no surface change (but see behavior, below).
The signature-invisible break: for exported functions whose bodies changed, scan the diff for changed return shapes, newly thrown/removed errors, changed side effects, and meaningful output-format changes (if the CLI's stdout is parseable, its format is public surface). A bugfix that consumers depend on (Hyrum's law) is technically PATCH — but call out high-blast-radius behavior fixes so the release notes can warn.
Phase 3 — The ruling
- The verdict: the minimum legal next version, stated plainly.
- The evidence: every MAJOR item (exact symbol, old vs. new, why it breaks a consumer — with a one-line hypothetical consumer that would break), then MINOR items, then notable PATCH-level behavior changes.
- The escape review: for each MAJOR item, whether a compatibility shim (deprecated alias, overload retained, default preserved behind an option) could legally demote the release to MINOR — with the shim sketched. Sometimes shipping the shim is an hour and skipping the major saves every consumer a migration.
- Release-notes draft: breaking changes first, each with its one-line migration instruction.
Rules
- Undocumented-but-exported is still public unless the ecosystem's convention clearly marks it internal.
- "Nobody uses that" is not a classification argument; it's a risk note.
- Be honest about limits: this analysis reads surfaces and diffs — deep behavioral equivalence isn't provable this way, and the report says which parts rest on body-diff heuristics.
1---2name: semver-cop3description: Determine whether the next release is legally a patch, minor, or major by diffing the public API surface against the last published version. Use before cutting a release, when reviewing "is this breaking?", or when writing honest release notes.4---56# Semver-cop78Semver is a legal system: the version number is a contract about what consumers can upgrade to blindly. Your job is to rule on the next release — patch, minor, or major — by *diffing the actual public surface*, not by skimming the changelog. Downgrading a breaking change to a minor is the crime; upgrading a patch to a major out of paranoia is just bad style. Rule precisely.910## Phase 1 — Establish the two surfaces1112- Find the last released version: registry (`npm view`, PyPI, crates.io) first, tags second; if they disagree, the registry is what consumers have — flag the drift.13- Check out the released version in a **separate worktree**. Never diff against "main from around then."14- Extract the **public surface** at both points, ecosystem-appropriate: exported symbols and their signatures, public types/interfaces and their fields, config options and their defaults, CLI commands/flags/exit codes, HTTP routes and payload shapes, error types consumers can catch. Type definition files, `__all__`, docs, and explicit export lists define "public"; note where the boundary is only conventional (underscore prefixes) and apply the *ecosystem's* convention, not your own.1516## Phase 2 — Classify every difference1718For each change to the surface:1920- **MAJOR** — removal or rename of anything public; signature narrowing (new required param, removed overload, narrowed input type); widened return/output type consumers must now handle; changed default that changes behavior; raised runtime/platform floor; error type or exit-code changes consumers may match on.21- **MINOR** — new exports, new optional params, widened *accepted* inputs, new config options with behavior-preserving defaults.22- **PATCH** — no surface change (but see behavior, below).2324**The signature-invisible break:** for exported functions whose *bodies* changed, scan the diff for changed return shapes, newly thrown/removed errors, changed side effects, and meaningful output-format changes (if the CLI's stdout is parseable, its format is public surface). A bugfix that consumers depend on (Hyrum's law) is technically PATCH — but call out high-blast-radius behavior fixes so the release notes can warn.2526## Phase 3 — The ruling27281. **The verdict:** the minimum legal next version, stated plainly.292. **The evidence:** every MAJOR item (exact symbol, old vs. new, why it breaks a consumer — with a one-line hypothetical consumer that would break), then MINOR items, then notable PATCH-level behavior changes.303. **The escape review:** for each MAJOR item, whether a compatibility shim (deprecated alias, overload retained, default preserved behind an option) could legally demote the release to MINOR — with the shim sketched. Sometimes shipping the shim is an hour and skipping the major saves every consumer a migration.314. **Release-notes draft:** breaking changes first, each with its one-line migration instruction.3233## Rules3435- Undocumented-but-exported is still public unless the ecosystem's convention clearly marks it internal.36- "Nobody uses that" is not a classification argument; it's a risk note.37- Be honest about limits: this analysis reads surfaces and diffs — deep behavioral equivalence isn't provable this way, and the report says which parts rest on body-diff heuristics.
tokyubevoxelverse