Versioning strategies
Version numbers are a contract — here's how to make them mean something.
Semantic versioning encodes intent as MAJOR.MINOR.PATCH, where each position signals breaking changes, new features, or fixes. Pre-release and build metadata annotate unstable builds, CalVer versions by date, and APIs are versioned through the URL path, a query parameter, or a header/media type.
Semantic versioning
SemVer expresses a release as three numbers, MAJOR.MINOR.PATCH, each carrying a defined meaning about compatibility. It turns an opaque number into a contract: by reading the version alone, a consumer can tell whether an upgrade is safe. This shared convention is why dependency managers can reason about which updates to accept automatically.
What a bump means
You increment MAJOR for a backward-incompatible (breaking) change, MINOR for new functionality that stays compatible, and PATCH for a backward-compatible bug fix. Bumping a higher position resets the lower ones to zero, so 1.4.2 to 2.0.0 signals 'this may break you.' Respecting these rules is what makes the promise trustworthy.
Pre-release and build metadata
Before a stable release you append a pre-release tag like 1.0.0-alpha.1 or -rc.2, which sorts as lower precedence than the final 1.0.0. Build metadata after a plus sign, such as +20240115 or +sha.5114f85, records how a build was produced without affecting precedence. These annotations let teams ship and identify unstable builds without polluting the release line.
Calendar versioning
CalVer drops compatibility semantics in favor of encoding the release date, as in 2024.01 or 24.1.0. It suits products where recency matters more than a breaking-change contract — operating systems, desktop apps, and rolling releases like Ubuntu. The trade-off is that the number no longer tells you whether an upgrade is safe, only when it shipped.
API versioning
Once other systems depend on your API, you version the interface itself so old clients keep working while you evolve. The three common approaches are the URL path (/v2/users), a query parameter (?version=2), or a header or media type (Accept: application/vnd.api.v2+json). URL versioning is the most visible and cache-friendly; header versioning keeps URLs clean at the cost of discoverability.
Why version numbers exist
Software changes constantly, and everyone who depends on it — other developers, other services, package managers, end users — needs a cheap way to answer one question: "if I take the newer version, will anything break?" A version number is a contract that answers exactly that. Without an agreed scheme, a version is just a meaningless label and every upgrade is a gamble.
The whole point of a versioning strategy is to make that number carry reliable, predictable meaning. Different strategies encode different things — compatibility, recency, or the shape of an evolving interface — but all of them exist to reduce the uncertainty of change. Getting versioning right is what lets thousands of interdependent packages upgrade automatically without constant breakage.
Semantic versioning and what a bump means
Semantic Versioning (SemVer) is the dominant convention, and it structures a release as three numbers: MAJOR.MINOR.PATCH, for example 2.4.1. Each position has a precise, agreed meaning tied to backward compatibility:
- MAJOR — increment for a backward-incompatible (breaking) change. Existing code may need to be updated to keep working.
- MINOR — increment when you add functionality in a backward-compatible way. Upgrading is safe; you just gain features.
- PATCH — increment for a backward-compatible bug fix. Nothing new, nothing broken.
Incrementing a higher-order position resets the lower ones to zero, so 1.4.2 becomes 2.0.0 for a breaking release. The power of SemVer is that the number alone communicates risk: a dependency manager can be told "accept any 1.x update" and trust that nothing labeled 1.x will break the caller. That trust only holds if maintainers honor the rules — which is why a version bump is best thought of as a promise, not a formality.
Pre-release tags and build metadata
Real releases aren't always stable, and SemVer has precise syntax for that. A pre-release identifier is appended after a hyphen — 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1 — to mark a build that is on the way to, but not yet, the final release. Crucially, a pre-release has *lower* precedence than its associated release, so 1.0.0-rc.1 sorts as older than 1.0.0. This lets teams publish and test release candidates without them being picked up as the stable version.
Build metadata is appended after a plus sign — 1.0.0+20240115 or 1.0.0+sha.5114f85 — and records how or when a particular build was produced. Unlike pre-release tags, build metadata is *ignored* when comparing precedence; two versions differing only in build metadata are considered the same release. Together these annotations give you a disciplined way to track the messy reality of alphas, betas, and CI builds without corrupting the clean release line that consumers depend on.
Calendar versioning
Not every project's most important signal is compatibility. Calendar Versioning (CalVer) encodes the release *date* into the version number instead — schemes like YYYY.MM (2024.01), YY.MINOR (24.1), or YYYY.0M.0D. Ubuntu's 24.04, released in April 2024, is the classic example.
CalVer shines when recency and cadence matter more than a formal breaking-change contract: operating systems, desktop applications, and continuously delivered products where "how current am I?" is the question users actually ask. It also communicates support windows and end-of-life naturally, since the date is right there in the number. The trade-off is the flip side of SemVer's strength — a CalVer number tells you *when* something shipped but not *whether* upgrading is safe, so projects that choose it must document compatibility separately. Some projects even blend the two, using a date-based major with SemVer-style minor and patch parts.
Versioning an API
Versioning a library is one thing; versioning a live API that other systems call in production is another, because you often must keep old clients working while you evolve the interface. There are three mainstream approaches, each with trade-offs:
- URL path versioning —
GET /v2/users. The version is explicit, highly visible, easy to route, and cache-friendly, which makes it the most common choice. The cost is that the version lives in the resource identifier, which some argue is impure REST. - Query parameter versioning —
GET /users?version=2. Simple to add and keeps a single base path, but it is easy to omit and can complicate caching and routing. - Header / media-type versioning —
Accept: application/vnd.api.v2+jsonor a customAPI-Versionheader. This keeps URLs clean and is considered the most RESTful, since the URL identifies the resource and the header negotiates its representation. The downside is discoverability: the version is hidden from anyone just reading URLs, and it is harder to test in a browser.
There is no universally correct answer. URL path versioning wins on clarity and tooling and dominates public APIs; header versioning wins on URL purity for teams that value it. What matters most is picking one scheme, applying it consistently, and treating each published version as a stable contract you will support for a defined lifetime — because the entire value of versioning, in libraries and APIs alike, is giving the people who depend on you a predictable, trustworthy signal about change.
Semantic versioning is MAJOR.MINOR.PATCH: breaking, backward-compatible feature, and backward-compatible fix.
Bump MAJOR for incompatible changes, MINOR for added features, PATCH for bug fixes — the number is a promise.
Pre-release tags (1.0.0-beta.1) and build metadata (+20240115) annotate builds that aren't stable releases.
Calendar versioning (CalVer) encodes the date, e.g. 2024.01, signaling recency over compatibility semantics.
APIs are versioned via URL path (/v2/users), query param (?version=2), or header/media type (Accept: application/vnd.api.v2+json).
The goal of any scheme is a predictable contract so consumers know whether upgrading is safe.
Quick quiz
In semantic versioning, when do you bump the MAJOR number?
Which is an example of header/media-type API versioning?
API design best practices
The conventions that make an API feel obvious instead of hostile.
Git branching workflows
The commit-to-merge loop every team runs — and the branching models that shape it.
CI/CD pipeline explained
Turn every commit into a tested, shippable, deployable artifact — automatically.
What is a REST API
The architectural style that made the web's APIs feel like the web itself.