What A Version Number Is Supposed To Promise

A jump from one version number to another is usually read as a measure of how much changed. Under the conventions most software libraries follow it means something narrower and far more useful: whether existing code will still work.

Three numbers, three different questions

The common scheme uses three parts separated by dots. The last part changes for fixes that alter no interface, and the middle part for additions that leave existing behavior intact.

The first part changes only when something that used to work stops working. That is the entire signal, and everything else in the scheme exists to keep that signal legible.

Read that way, a version number answers a maintenance question rather than describing effort. A large internal rewrite that breaks nothing does not require a first-part increase.

The promise is aimed at machines

Projects declare which versions of a dependency they accept, usually as a range that permits anything up to the next breaking change.

Package managers use those ranges to choose versions automatically, so a scheme applied honestly lets an enormous number of updates install without any human reviewing them.

Applied dishonestly, it produces builds that break on a routine update, and the ecosystem's answer is lock files that pin exact versions regardless of what the ranges permit.

Breaking changes are hard to define

Anything observable can become something a user depends on, including error message wording, the order of results, and behavior in cases the documentation never addressed.

A maintainer who fixes a genuine bug can break code written around that bug, which leaves an open question about whether the fix deserves a first-part increase.

Different projects answer differently, so the number is a statement of intent by the maintainer rather than a fact any tool has verified.

Consumer software abandoned the scheme entirely

Applications sold to people rather than consumed by other code have no compatibility contract to express, so their numbers serve marketing and release cadence instead.

Some products number by year, some by internal build, and some skip numbers judged unappealing. None of this is wrong, but it means the number carries no technical meaning.

Continuously delivered web software often shows no version at all, because there is only ever one deployed version and nobody chooses which one to run.

Pre-release labels move the rules

A suffix marks a build as not yet covered by the compatibility promise, which is how projects publish work in progress without claiming stability for it.

A leading zero in the first position carries the same meaning across a whole project, signaling that the interface is still moving and no guarantee applies yet.

Projects can sit at that leading zero for years, and the practice is honest even when it is inconvenient, because the alternative is a promise nobody intends to keep.