Software versioning: the main schemes and how to pick
7 min read
Software versioning is the practice of giving each release a unique identifier, usually a number, so that people and tools can tell versions apart, put them in order and see what changed between them. Three schemes cover most products: semantic versioning, where the number signals compatibility; calendar versioning, where it records the release date; and a plain build number that only goes up. Many products use two at once, a readable version for people and an internal one for machines.
| Scheme | Example | What the number tells you | Where you see it |
|---|---|---|---|
| Semantic versioning | 3.2.1 | Whether upgrading can break your code | Libraries, packages, public APIs |
| Calendar versioning | 26.04 | When the release came out | Ubuntu (YY.0M), yt-dlp (YYYY.0M.0D) |
| Four-part build version | 1.0.154.65 | The milestone, and exactly which code | Chrome and Chromium |
| Internal build number | 42 | Which build is newer, nothing more | Android’s versionCode |
What is software versioning?
It is how a team labels releases so that each one can be referred to, compared and installed on purpose. A good version identifier is unique, always increases, and tells its reader something useful, whether that is the compatibility of an upgrade or the age of a build.
The reader matters more than the format. A developer deciding whether to upgrade a dependency needs to know if it will break their code. An operations team planning support needs to know how old a release is. A package manager needs only to sort versions correctly. Each scheme below serves one of these readers first, and choosing well starts with knowing which reader yours is.
What are the main software versioning schemes?
Semantic versioning, calendar versioning, and plain or composite build numbers. Most others are variations on these three.
Semantic versioning. The SemVer 2.0.0 specification says to increment MAJOR “when you make incompatible API changes,” MINOR “when you add functionality in a backward compatible manner,” and PATCH “when you make backward compatible bug fixes.” The number is a promise about compatibility, which is why it suits code that other code depends on.
Calendar versioning. CalVer describes “a time-based element, usually part of the release date,” and rather than fixing one format it defines tokens such as YYYY, YY, 0M and 0D that projects combine. Its examples include 26.04 for Ubuntu (YY.0M) and 2026.08.19 for yt-dlp (YYYY.0M.0D).
Build numbers. A counter that increases with every build, sometimes combined with other parts. Chromium’s version numbers “consist of 4 parts: MAJOR.MINOR.BUILD.PATCH,” where the BUILD number “is always increasing as the source code trunk advances.”
When should you use semantic versioning?
When other people’s code depends on yours and they need to know whether an upgrade is safe. Libraries, SDKs, command-line tools used in scripts and versioned APIs all fit.
The scheme only works if the bumps are honest. SemVer says that once a version is released, “the contents of that version MUST NOT be modified,” and that a major version “MUST be incremented if any backward incompatible changes are introduced to the public API.” A release that breaks callers under a minor bump teaches everyone downstream to pin exact versions, which defeats the point. Deciding what counts as incompatible is the hard part; breaking changes covers that question, and semantic versioning and your changelog covers how each bump maps to a changelog entry.
Before 1.0.0 the rules are looser by design. In the spec’s words, “Major version zero (0.y.z) is for initial development. Anything MAY change at any time,” while “Version 1.0.0 defines the public API.”
When does calendar versioning make more sense?
When the date says more than a compatibility promise could. CalVer’s own FAQ points to projects with “a large or constantly-changing scope” like Ubuntu, products for “non-technical audiences, who shouldn’t have to understand if a change is ‘breaking’,” and projects driven by outside events: support schedules, certificate updates in certifi, timezone changes in the IANA database.
CalVer is open about what it leaves out: it “deliberately does not attempt to communicate breaking changes.” The same FAQ answers that gap directly: “There is no substitute for a changelog and policy,” and it suggests pairing a calendar version with a time-based deprecation policy, citing Twisted’s rule of one year and two releases between deprecating something and removing it.
Calendar versions also fit a fixed release schedule well, because the version follows from the date. Ubuntu releases every six months and its versions say which month. If you are deciding how often to ship in the first place, release cadence compares the schedules large projects use.
Why do apps have two version numbers?
Because people and machines need different things from a version. People want something readable that matches the marketing; the system needs a number that only ever goes up.
Android makes the split explicit. Its versioning guide defines versionCode as “a positive integer used as an internal version number” that the system uses “to protect against downgrades,” and says it is “not the version number shown to users.” The user-facing one is versionName, which “is the only value displayed to users.” Chromium draws the same line inside one string: MAJOR and MINOR “reflect a scheduling or marketing decision rather than anything about the code itself,” while “the BUILD and PATCH numbers together are the canonical representation of what code is in a given release.” For store listings, mobile app release notes covers whether the version belongs in the note text at all.
How do pre-release versions work?
They mark a build that is not final yet, and every scheme that supports them sorts them before the release they lead up to.
SemVer adds a hyphen and identifiers after the patch number, so 1.0.0-alpha comes before 1.0.0; the spec states that “a pre-release version has lower precedence than a normal version.” Python’s version specifiers define the scheme [N!]N(.N)*[{a|b|rc}N][.postN][.devN], so 3.13.0a1, 3.13.0b1 and 3.13.0rc1 all sort before 3.13.0. What each stage means in practice is covered in alpha vs beta testing and release candidate.
What if your product has no version numbers?
Then the date of each change does the job, and versions matter only at the edges where someone integrates with you. Many web applications deploy continuously and never show users a version, and a dated changelog tells them what changed and when.
The edges are APIs, SDKs and anything embedded in another site. Stripe versions its API by date, for example, so a request can pin the behavior it was written against, as described in Stripe API versioning. Changeloop’s embeddable widget has two script URLs: /widget.js always serves the newest build, while /widget-vN.js pins one build whose bytes never change once that version number has been served, as the widget docs explain. The versioned URL exists for teams that would rather adopt changes on purpose.
How do you choose a software versioning scheme?
Pick for your main reader, then make the rules written and boring. These questions decide most cases:
- Does other code depend on yours? Use semantic versioning, and treat a major bump as a migration you have to document.
- Do readers care most about age and support windows? Use a calendar version, and publish the support policy next to it.
- Is the version only for your own build system? A counter is enough; keep it out of user-facing text.
- Do you have two audiences? Use two numbers, like Android’s
versionCodeandversionName, rather than one that serves neither.
Whichever you choose, tag each release in git so the version maps to exact code, and give every version a changelog entry. Git tags and releases covers the tagging side, and the changelog generator turns a list of commits into a draft entry for the version you just tagged.
FAQ
What is the difference between software versioning and version control? Version control records every change to the source code, commit by commit. Software versioning labels the releases you ship from it, and a git tag is usually what connects a version number to the exact commit it was built from.
What does version 1.0.0 mean? Under semantic versioning it is the first version with a stable public API, and from then on breaking changes require a new major version. Before 1.0.0 the specification allows anything to change at any time.
Can you switch versioning schemes later? Yes, but new versions must still sort after old ones. Python’s version specifiers include an epoch, written as a number and an exclamation mark before the version, for exactly this case: a project moving from date-based versions like 2014.04 to versions like 1.0 would otherwise see its new releases sorted as older.
Should the version number appear in the changelog? Yes. Each changelog section should carry the version and the release date, so readers can match what they have installed to what changed. For products without versions, the date alone is enough.
The technical claims in this article have not been independently reviewed. If something here is wrong, tell us and we will correct it.