Choose the Correct Semver Bump
The version number is a contract with consumers. Guessing "patch" for a breaking change breaks everyone who trusted the number. Decide from the actual API diff, not from the size of the commit.
Procedure
- Generate the public-surface diff between the last release and HEAD:
- Rust:
cargo public-api diff <prev>orcargo semver-checks check-release. - Go:
go-apidiff v1.2.0 HEADorapidiff -wwithgolang.org/x/exp/apidiff. - TypeScript:
api-extractor run --localthen diff the.api.mdreport. - Java:
japicmp -o old.jar -n new.jarprints added/removed/changed members.
- Rust:
- Classify each change:
- Removing or renaming an exported symbol, tightening a parameter type, or adding a required argument → MAJOR.
- Adding an exported symbol, an optional parameter with a default, or a new enum member consumers may match on → MINOR.
- Fixing behaviour that did not match docs, perf work, internal refactor → PATCH.
- Read the changelog for behavioural breaks the API diff cannot see: changed default values, stricter validation, a different error type. These are MAJOR even though signatures are unchanged.
- Apply the 0.x rule: while
major == 0, a MINOR bump may break compatibility. Still bump MINOR for additions and PATCH for fixes; document breaks in the changelog. - If both a break and an addition landed, the bump is MAJOR — the highest class wins.
- Record the decision in the PR: "MAJOR because
parseConfiggained a requiredoptsargument." - Use
cargo semver-checks/japicmpin CI as a gate; let a tool catch the missed bump.
Pitfalls
- Adding a method to an interface others implement is a break for implementers, even though it is "additive" for callers.
- Changing an error message that tests assert on is a break for those consumers; keep messages stable or gate them.
- Pre-release identifiers order oddly:
1.0.0-rc.2precedes1.0.0, and1.0.0-alpha<1.0.0-beta. - Build metadata (
+build.5) is ignored in precedence, so it can never carry a compatibility signal. - Bumping two of three numbers (
1.2→1.3.0vs1.2.0→1.3.0) signals the wrong thing; always three.
Verification
cargo semver-checks check-release # or: japicmp -o prev.jar -n new.jar --only-modified
The tool reports the required bump as MAJOR/MINOR/PATCH; confirm it matches the version you wrote in the manifest.
Report: "Choosing <major|minor|patch> →: <tool> reports breaking and additive changes, breaks are ."