Semantic versioning: a major bump promises no silent behavior change
MAJOR does not mean big. It means breaking. Using it for refactors and hiding breaks in minor releases turns your downstream automatic upgrades into outages.
1.4.2 → 1.5.0 says added features, nothing broken. The real value of that promise is that downstream can write ^1.4.2 and skip per-release review. What it commits to is not how large a change is, but whether a break can happen silently.
What the three numbers mean
| Position | Bump when | Downstream may assume |
|---|---|---|
| MAJOR | any incompatible change | a human must intervene |
| MINOR | backward-compatible additions | upgrading is safe |
| PATCH | backward-compatible fixes | upgrading is safe |
Everything rests on the definition of backward compatible. Changing a default argument, removing a console.log, altering sort stability: all tiny, all breaking.
The 0.x special case
During 0.y.z, any release may break. Semantically, ^0.4.2 does not promise that 0.5 is compatible.
npm special-cases this: ^0.4.2 actually allows only 0.4.x. That behavior is widely misunderstood and explains many “my automatic upgrade did not upgrade” puzzles.
Three questions before publishing
- Does old code still work on the new version? If no, MAJOR.
- Is there a new public API? If yes, MINOR.
- Is it only an internal fix? If yes, PATCH.
If the answer is “the interface is the same but the behavior changed”, that is still MAJOR. Observable runtime changes are breaking too — and that is the class most easily missed, because type checking cannot see it.
Prerelease and build metadata
In 1.5.0-beta.1 the beta.1 part is a prerelease identifier and sorts below 1.5.0. With <, 1.5.0-beta.1 < 1.5.0 holds.
In 1.5.0+build.7 the +build.7 is metadata only and takes no part in comparison. Fine for carrying build info, surprising if you sort by it.
Lockfile and range are two things
The range in package.json states intent; the lockfile pins the resolution. Commit only the former and different machines install different versions — the classic source of “works on my machine”.
A major bump says “read the migration notes”. Do not say it casually, and do not stay silent when you should say it.
Comments
…