Semantic Versioning¶

Versioning convention — instantiates Compatibility Management

Encodes the compatibility relationship between releases into a MAJOR.MINOR.PATCH number, so a dependent can predict what will break before upgrading — without reading the diff.

Version: v1 · 2026-08-24 · History
Mechanism #: 8161
Type: Method
Form family: Rule, Policy & Commitment
Solution family: Ordering, Sequencing & Dependencies
Problem family: Composition, Interface & Interoperability Failure
Problem subfamily: Protocol, Schema & Encoding Incompatibility
Origin domain: Computer Science & Software Engineering
Also from: Engineering & Design, Organizational & Management Science
Instantiates: Compatibility Management
Also instantiates: Versioned Evolution

Semantic Versioning turns the compatibility relationship between two releases into an arithmetic one. Every release carries a three-part number — MAJOR.MINOR.PATCH — and each position is a promise: increment PATCH for a backward-compatible fix, MINOR for a backward-compatible addition, and MAJOR only when something that used to work stops working. The distinctive move is that the rule lives in the number: a dependent can compare 2.4.1 to 2.7.0 and know the upgrade is safe, or to 3.0.0 and know it is not, without inspecting a single line of the change. It is a signalling convention, not an enforcement mechanism — it states a compatibility claim compactly enough that both humans and package managers can act on it at ecosystem scale.

Example¶

A widely used open-source JSON-schema validation library sits at 2.4.1. Three changes land. A maintainer fixes a crash on empty input — nothing callers can observe changes, so it ships as 2.4.2. Someone adds an optional new validation keyword; existing schemas behave identically, so it ships as 2.5.0. Then a contributor removes a long-deprecated config flag, and any project still passing that flag will now error. Because that removes existing behaviour, the rule forces the next release to be 3.0.0, not 2.6.0.

The payoff shows up downstream. Thousands of applications depend on the library with a range like ^2.4.1 — "any 2.x at or above this." Their package managers silently pull in 2.4.2 and 2.5.0 on the next install and refuse to jump to 3.0.0 on their own. No one read the changelog; the number did the gatekeeping. The single deliberate act — judging the flag removal a MAJOR event — is what protected every one of those dependents from a surprise break.

How it works¶

The three-part contract. MAJOR = incompatible change; MINOR = compatible addition; PATCH = compatible fix. The compatibility rule is read off the leftmost digit that moved.
The boundary rule. MAJOR increments exactly when — and only when — a change breaks an existing consumer. That single condition is what the whole scheme hangs on.
Ordering and precedence. Numbers sort, so "newer," "older," and "how far apart" are all computable, and pre-release tags (-rc.1) sort below their final release.
Ranges and pinning. Dependents declare which band they accept (^, ~, exact pins); the scheme lets them opt into automatic compatible upgrades while excluding the incompatible ones.

Tuning parameters¶

What counts as "breaking" — whether MAJOR is reserved for documented-API changes or triggered by any observable behaviour change. Stricter definitions bump MAJOR more often: more honest, but more churn for dependents.
The 1.0 commitment — staying in 0.y.z means "anything may change and nothing is promised." Declaring 1.0.0 is the moment the compatibility rule becomes binding; delaying it buys design freedom at the cost of withholding any guarantee.
Release granularity — whether one number covers a whole package or each module versions independently. Finer granularity gives truer signals but multiplies the numbers to track.
Pre-release channels — how much you lean on alpha/beta/rc tags to ship ahead of the stable promise without spending a real version.

When it helps, and when it misleads¶

Its strength is compression: it collapses "is this upgrade safe?" into a comparison a machine can make, which is what makes automated dependency resolution across an ecosystem of thousands of packages possible at all. It also creates shared vocabulary — "that's a major bump" instantly communicates scope.

Its central weakness is that the number is a promise, not evidence. A release labelled 2.5.0 that actually breaks callers is worse than an unlabelled one, because everyone trusted the label and upgraded automatically. Two misuses corrupt the signal from opposite directions: inflating MAJOR for marketing weight — a headline 4.0 over a modest change — and suppressing a MAJOR bump to avoid looking unstable, shipping real breaks as minor releases. The discipline that keeps it honest is to tie the MAJOR decision strictly to the specification's rule — increment for any backward-incompatible change, and only for that^[n1] — rather than to judgement, optics, or convenience, and to pair the numeric claim with a suite that tests it rather than trusting the digit alone.

How it implements the components¶

Semantic Versioning fills only the signalling components — it declares the relationship, it does not build or verify it:

compatibility_rule — the MAJOR.MINOR.PATCH contract is a compatibility rule: same MAJOR means compatible, and the digit that moved tells you whether interaction is safe. The rule is stated as arithmetic.
breaking_change_boundary — a MAJOR increment is precisely the public declaration of a breaking-change boundary: the point at which old assumptions stop holding.

It does not map concrete version combinations (that is Compatibility Matrix), keep old versions working (support_window, fallback_or_graceful_degradation_rule — Backward Compatibility Policy), move anyone across the boundary (Schema Migration, Migration Guide), or verify that the claim is true (Compatibility Test Suite). A version number asserts; the siblings implement and check.

Instantiates: Compatibility Management — Semantic Versioning is the signalling layer that lets the rest of the machinery reason about which releases relate how.
Sibling mechanisms: Backward Compatibility Policy turns the promise into an obligation; Migration Guide helps dependents cross a MAJOR boundary. Compatibility Matrix · API Versioning · Compatibility Test Suite · Support Lifecycle Schedule

Editorial Notes¶

Form Classification¶

Form family: Rule, Policy & Commitment

Rationale: Semantic Versioning operates as a standing rule, threshold, contractual commitment, or policy constraint governing future conduct because it encodes the compatibility relationship between releases into a MAJOR.MINOR.PATCH number, so a dependent can predict what will break before upgrading — without reading the diff.

Independent corroboration: The frozen evidence defines Semantic Versioning as 'Encodes the compatibility relationship between releases into a MAJOR.MINOR.PATCH number, so a dependent can predict what will break before upgrading — without reading the diff', so its operative form is Rule, Policy & Commitment.

Review outcome: Independent reviewer agreement; medium confidence.

Origin Attribution¶

Primary origin: Computer Science & Software Engineering

Origin pattern: Single lineage

Present-day reach: Specialized

Rationale: MAJOR.MINOR.PATCH compatibility signaling is the explicitly named Semantic Versioning convention of software package and API ecosystems.

Related originating lineages:

Engineering & Design — Engineering design, reliability, and systems-safety practice supplies a parallel or contributing lineage for the mechanism's defining operation: encodes the compatibility relationship between releases into a MAJOR.MINOR.PATCH number, so a dependent can predict what will break before upgrading — without reading the diff.
Organizational & Management Science — Release governance institutionalizes who declares breaking, additive, and corrective change.

Review resolution: The blind reviewers agree that computer_science is the primary origin and differ only on alternate origin disagreement. I preserve every independently explained alternate from both records rather than imposing a numeric cap. I retain single_lineage because the combined record shows one traceable formative lineage. The broader reach of specialized records portability separately from historical provenance, and encyclopedia_synthesis=false preserves the affirmative synthesis judgment where either reviewer identified one.

Review outcome: Reconciled after independent review; high confidence.

Notes¶

[n1] The Semantic Versioning 2.0.0 specification (semver.org) sets the governing rule: MAJOR must increment for any backwards-incompatible public change. The misuses above are departures from it in opposite directions — inflating MAJOR for weight it did not earn, or suppressing it to appear stable. ↩