Reading a Version Number: Major, Minor, Patch
Studio Editorial | Digital Publishing
“ A label such as v2.1.2 looks like a small piece of technical housekeeping. In fact, it is a compact promise. Each digit tells you what has changed, how much has changed and whether what worked yesterday will still work today — if you know how to read it. ”
Every app on your phone, every program on your computer and every page of code behind a website carries a small label of numbers and dots. Most people never look at it. Those who do can learn a great deal from three digits.
A version number is the name a piece of work gives to one particular moment in its life. It answers a simple but important question: which copy is this? When a program is fixed, improved or rebuilt, the new copy needs a new name, so that people can tell it apart from the old one, report problems accurately and decide whether it is safe to upgrade.
Writers and publishers have always understood this need. A manuscript passes through drafts; a book passes through editions and printings. Software simply made the problem more urgent. A program may change every week, and thousands of other programs may depend on it. Without a clear, shared way of naming each change, the whole system would become guesswork.
The most widely used answer to that problem is a three-part number such as 2.1.2. This article explains what each part means, how the numbers move, what the letters and symbols around them signify, and why not every version number follows the same rules.
Anatomy of v2.1.2
The modern convention is called Semantic Versioning, often shortened to SemVer. It was written by Tom Preston-Werner, a co-founder of GitHub, and published at semver.org; version 2.0.0 of the specification, the one still in use, appeared in 2013. Its central idea is that a version number should carry meaning. Each of the three positions answers a different question about the change.
In the specification’s own words, you increment the MAJOR version “when you make incompatible API changes”, the MINOR version “when you add functionality in a backward compatible manner” and the PATCH version “when you make backward compatible bug fixes”.
An API — an application programming interface — is simply the public face of a program: the functions, commands, settings or formats that other people and other programs rely on. The key word throughout is compatible. The question each digit answers is not “how much work went into this?” but “will this change disturb the people who already use it?”
Read this way, v2.1.2 says a great deal: this is the second generation of the product; it has gained one round of new features since that generation began; and it has received two rounds of bug fixes since those features arrived.
How the digits move
A version number behaves rather like the odometer in a car, with one important difference: when a higher digit goes up, every digit to its right returns to zero. The specification is explicit about this. The patch number resets when the minor number increases, and both reset when the major number increases.
Two further rules keep the system honest. First, each part must be a whole, non-negative number without leading zeros — 2.1.2, not 2.01.02. Second, once a version has been released, its contents must never be altered. If something is wrong with 2.1.2, the fix becomes 2.1.3. A version number is a name for one fixed thing, and the name must not quietly come to mean something else.
Numbers, not decimals
The most common misreading of version numbers comes from school arithmetic. Because the parts are separated by dots, it is tempting to read them as decimal fractions. They are not. Each part is a separate whole number, counted on its own.
So the sequence 1.8.0, 1.9.0, 1.10.0, 1.11.0 is perfectly normal, and a program can reach version 4.27.103 without anything unusual having happened. Comparing two versions means comparing the major numbers first; only if they are equal do you compare the minor numbers, and only if those are equal do you compare the patches.
Before 1.0, and the meaning of 1.0.0
Many projects begin life with a version number that starts with zero, such as 0.3.1. Semantic Versioning gives this a precise meaning: “Major version zero (0.y.z) is for initial development.” While the first digit is zero, anything may change at any time, and nobody should treat the program as stable.
That makes 1.0.0 a genuine milestone rather than a vanity number. According to the specification, “Version 1.0.0 defines the public API.” It is the moment the makers say, in effect: this is the shape of the thing, and from now on we will tell you, through the version number, whenever we change it in a way that matters.
Alpha, beta and release candidates
Before a version is finished, its makers often want people to test it. Semantic Versioning allows a pre-release label to be attached with a hyphen: 2.2.0-alpha, 2.2.0-beta.2, 2.2.0-rc.1. The traditional sequence is:
Alpha — early and incomplete; features may still be missing or unstable. Beta — feature-complete, but still being tested and corrected. Release candidate (rc) — believed to be ready; released for final checks, and published unchanged if no serious problem appears.
A pre-release always ranks below the finished version it leads to. So 2.2.0-rc.1 comes before 2.2.0, not after it. The specification gives a full example of the order:
A second, rarer addition is build metadata, attached with a plus sign: 1.0.0+20130313144700 or 1.0.0-beta+exp.sha.5114f85. It records information about how a particular copy was produced — a date, a build number, an identifier from the code repository — but it is deliberately ignored when deciding which version is newer.
What about the “v”?
Strictly speaking, the letter is not part of the number. The Semantic Versioning specification addresses this directly: “v1.2.3” is not itself a semantic version, but “prefixing a semantic version with a ‘v’ is a common way (in English) to indicate it is a version number.” So v2.1.2 and 2.1.2 name the same release. The “v” is a label on the jar, not part of its contents — useful in a sentence, a file name or a heading, where a bare 2.1.2 might be mistaken for a date, a price or a section number.
Why the promise matters
The real value of Semantic Versioning becomes clear when programs depend on one another. A modern website or app may be assembled from hundreds of smaller packages written by other people. Each of those packages keeps changing. The version number is how the builder decides, automatically and safely, which updates to accept.
Package managers turn the meaning of the digits into rules. In the widely used npm system for JavaScript, for example, a caret or a tilde in front of a version sets the range of updates that may be installed:
This only works if the people publishing the packages keep their side of the bargain. If a breaking change is slipped into a patch release, thousands of projects that trusted the number may break overnight. That is why the discipline matters more than the digits themselves. A version number is useful exactly to the extent that it is honest.
The same discipline governs how features are retired. Semantic Versioning recommends that a feature should first be marked as deprecated — still working, but officially on its way out — in at least one minor release, before it is finally removed in a new major release. Users get warning; the major number tells them when the warning has come true.
Not every version number is semantic
Semantic Versioning is widespread, but it is a convention, not a law. Many respected projects number their releases in other ways, each suited to its own purpose. Before reading meaning into a version number, it is worth knowing which system produced it.
Calendar versioning, or CalVer, uses the release date as the number. Ubuntu’s versions follow a year-and-month pattern, so 24.04 means April 2024; the Python installer pip uses the year followed by a release count. Such numbers say nothing about compatibility, but they tell you at a glance how old a release is.
Four-part versions add a further level of detail. Microsoft’s .NET defines its version as major, minor, build and revision. A different build number usually means the same source code recompiled; a different revision is intended to be fully interchangeable — a security fix, for example.
The Linux kernel says plainly in its own documentation that it does not use Semantic Versioning. A new kernel arrives every two or three months and its second number simply increases; when that number is judged large enough, the first number goes up instead — which is how Linux 4.20 was followed by 5.0. Fixes to an existing kernel are then released with a third number, as in 5.2.21.
Web browsers use a release train: a new major version leaves on schedule whether its changes are large or small. Google moved Chrome to a new milestone every four weeks starting with Chrome 94 in 2021, and Mozilla moved Firefox to a four-week cycle in 2020. That is why browser numbers are now in the hundreds; a high major number there means a long history, not a long list of breaking changes.
Marketing versions are chosen for the public rather than the engineers. Sun Microsystems released Java “5.0” in 2004, while the version string inside the software still read 1.5.0. Years later, the version-string scheme introduced with Java 9 dropped the old “1.” prefix entirely. The public name and the technical name had simply drifted apart.
The curious case of TeX
The most eccentric version number in computing belongs to TeX, the typesetting system created by the computer scientist Donald Knuth and still used for mathematical and scientific publishing. Knuth decided that TeX was essentially finished. From version 3 onwards, instead of counting up, each update would add one more digit of π.
3.1
3.14
3.141 …
3.141592653 (2021)
The current version of TeX is 3.141592653, last updated in 2021. Its companion program, METAFONT, approaches the number e in the same way and stands at 2.7182818. Knuth has said that after his death the version number will be set to Ï€ itself, and any remaining bugs will become permanent features. The joke carries a serious idea: a version number can express a philosophy. TeX’s numbers say that the work is not growing any more, only becoming more exact.
Publishers were versioning first
Long before software, the book trade developed its own versioning system — and its logic is remarkably close to Semantic Versioning.
A new edition of a book means the text has been substantially revised: chapters added, rewritten or removed. Page numbers no longer match, and a citation to the old edition may not work for the new one. That is a major version. A new printing, or impression, reproduces the same edition, perhaps with a handful of typographical errors corrected. Page numbers stay the same, and every reference remains valid. That is a patch.
Readers, librarians and scholars rely on these distinctions for the same reason programmers rely on version numbers: to know exactly which text is in front of them. When a reference in a Nevalor Post article cites a particular edition, it is doing precisely what a dependency list does in software — naming the version that the argument was built upon.
The changelog: the story behind the number
A version number tells you how much has changed. It cannot tell you what. That is the job of the changelog, a plain record of the notable changes in each release. The widely followed guide Keep a Changelog, created by Olivier Lacan, recommends that changelogs be written for people rather than machines, that every version have an entry with its release date, that the latest version come first, and that changes be grouped under six headings: Added, Changed, Deprecated, Removed, Fixed and Security.
### Fixed
– Chapter links no longer open the wrong page on mobile.
– Curly quotation marks now display correctly in titles.
## [2.1.0] — 2026-09-28
### Added
– Readers can now bookmark a chapter.
### Deprecated
– The old print layout; it will be removed in 3.0.0.
Notice how the changelog and the number support each other. Version 2.1.0 added a feature, so the minor digit rose. Version 2.1.2 only fixed problems, so only the patch digit moved. And the deprecation warning tells readers, well in advance, that the next major version will remove something.
Versioning your own work
Version numbers are not only for large software companies. Anyone who edits the same file repeatedly — a web page, a template, a manuscript, a design — benefits from naming each copy clearly. At Nevalor, every piece of code delivered for the website carries a version number in its opening HTML comment, so that the right copy is always the one that gets pasted. The same habit serves a writer revising a novel or an editor preparing a page.
In the file’s header, the page’s footer or the book’s copyright page — not only in your head.
Even the smallest released change deserves a new number.
Once v2.1.2 exists, it means one thing forever.
Fixes move the last digit; additions move the middle; upheavals move the first.
A few lines of changelog turn a number into a history.
The next time an app asks you to update to version 2.1.2, the number will no longer be a meaningless string. You will know that you are on the second generation of the program, that it has gained one round of new features, and that this update — moving only the last digit — fixes problems without asking you to relearn anything.
Three small digits, two dots and an optional “v”. Read carefully, they tell the story of a piece of work: where it began, how it has grown and how much its makers can be trusted to keep their word.
Studio Editorial | Digital Publishing
Version numbers, semantic versioning and release practice
Editorial Note
References and further study
Chromium Blog. “Speeding Up Chrome’s Release Cycle.” March 4, 2021.
Coghlan, Alyssa, and Donald Stufft. “PEP 440 – Version Identification and Dependency Specification.” Python Enhancement Proposals. Accessed October 12, 2026.
Hashemi, Mahmoud. “Calendar Versioning.” CalVer. Accessed October 12, 2026.
Knuth, Donald E. “The Future of TeX and METAFONT.” TUGboat 11, no. 4 (1990): 489.
Kothari, Ritu, and Yan Or. “Moving Firefox to a Faster 4-Week Release Cycle.” Mozilla Hacks, September 2019.
Lacan, Olivier. “Keep a Changelog 1.1.0.” Keep a Changelog. Accessed October 12, 2026.
Linux Kernel Documentation. “How the Development Process Works.” The Linux Kernel. Accessed October 12, 2026.
Microsoft. “Version Class (System).” Microsoft Learn: .NET API Reference. Accessed October 12, 2026.
npm. “node-semver: The Semantic Versioner for npm.” GitHub. Accessed October 12, 2026.
OpenJDK. “JEP 223: New Version-String Scheme.” OpenJDK. Accessed October 12, 2026.
Preston-Werner, Tom. “Semantic Versioning 2.0.0.” Semantic Versioning. Accessed October 12, 2026.
Sun Microsystems. “Version 1.5.0 or 5.0?” J2SE 5.0 Release Notes. Santa Clara, CA: Sun Microsystems, 2004.
Ubuntu. “Releases.” Ubuntu Wiki. Accessed October 12, 2026.
Comments