Skip to content

Semantic Versioning or Release Scheme

Release-numbering protocol — instantiates Open Reuse Publication Infrastructure

A release-numbering scheme whose version numbers themselves encode compatibility — signaling whether an update is safe, additive, or breaking — so dependents can upgrade on rules rather than by re-testing everything.

Once strangers depend on an artifact, every new release is a question: will this break me? Semantic Versioning or Release Scheme answers it in the version number itself. Rather than an opaque ordinal, a structured scheme makes the number a machine-readable compatibility promise — under SemVer, MAJOR.MINOR.PATCH, where a major bump means "breaking," a minor means "additive, safe," and a patch means "fix, safe." Its defining move is to encode the compatibility class of a change in the identifier, so a dependent — or its resolver — can decide whether to take an update by rule instead of by re-testing everything. Where a changelog narrates what changed and a deprecation feed broadcasts end-of-life, the version scheme compresses the single most consequential fact — is this safe to adopt — into a number a tool can act on automatically.

Example

A company maintains a shared design-system component library used by dozens of internal apps. Before adopting a scheme, every release triggered the same fire drill: each app team re-tested against the new build because a "small update" might silently change a button's API. So the library adopts Semantic Versioning (SemVer 2.0.0). Now 1.4.2 → 1.4.3 is a bug fix, 1.4 → 1.5 adds components without breaking anything, and 1.x → 2.0 changes an API and demands a migration.

App teams pin ^1.4 (a caret range), so their build automatically takes minor and patch updates but holds at the major boundary until they schedule the 2.0 migration deliberately. The upgrade question — "is this safe?" — went from a manual re-test to a rule the dependency resolver applies on its own. The library ships no faster; it just stopped forcing every consumer to re-verify compatibility by hand, because the number now carries that answer.

How it works

What distinguishes a versioning scheme from "increment a counter" is that the increment means something the consumer can rely on:

  • Compatibility encoded in the number. Each position signals a class of change — breaking, additive, or fix — by a shared rule, not by prose.
  • A public promise, not a private habit. The scheme is a stated contract about what each kind of bump guarantees, so consumers can trust it without asking.
  • Machine-actionable ranges. Because the number encodes compatibility, resolvers can safely auto-adopt some updates and pin against others.
  • Channels for the not-yet-stable. Pre-release and build lanes (alpha, beta, rc) let consumers opt into the unfinished without it masquerading as stable.

Tuning parameters

  • Scheme choice — SemVer (compatibility-encoding) vs. CalVer (date-based) vs. an internal convention. SemVer maximizes machine-actionable compatibility; CalVer instead signals recency and cadence.
  • Breaking-change threshold — how strictly "breaking" is defined (any observable change vs. a change to the documented contract). Strict definitions mean frequent majors; loose ones mean surprise breaks slipped in as minors.
  • Pre-release and channel policy — which alpha/beta/rc lanes exist and how consumers opt in, trading early access against stability guarantees.
  • Deprecation window — how long a deprecated feature survives across releases before a major removes it. Longer windows ease migration; shorter ones cut maintenance drag.
  • Range and pinning guidance — what pinning discipline you recommend consumers adopt (caret, tilde, exact), which shapes how automatically your updates flow downstream.

When it helps, and when it misleads

Its strength is turning "is this upgrade safe?" from a re-test into a rule: automated resolvers can adopt safe updates, teams can schedule breaking ones deliberately, and a breaking change becomes visible before install rather than after it detonates.

Its failure mode is that the number is only as honest as the maintainer. Shipping a breaking change as a minor — or over-bumping out of caution — poisons the contract, and consumers who upgraded on trust break worse than if there had been no scheme at all. There is also an irreducible gap: "breaking" is judged against the publisher's stated contract, but consumers depend on more than the contract, so a technically-compliant minor can still break someone relying on unpromised behavior. This edges toward dependency hell, the tangle of incompatible version constraints a scheme is meant to tame but cannot fully banish.[1] The discipline that keeps it honest is defining compatibility precisely, testing for breaks before choosing the increment, and pairing the scheme with a narrative changelog and a deprecation policy.

How it implements the components

Semantic Versioning or Release Scheme fills the compatibility-signaling slice of the archetype — the components a release scheme genuinely operates:

  • versioned_release_record — the scheme structures each release into an ordered, compatibility-typed record consumers can reason about and pin to.
  • change_notification_and_deprecation_policy — the version increment is the primary machine-readable change signal (a major bump announces a break), and the scheme sets the deprecation window a feature survives before removal.

It does not narrate what changed in prose (Changelog and Release Notes), broadcast individual end-of-life events (Deprecation Notice Feed), mint the artifact's identity (persistent_address_and_identifier — Persistent Identifier Minting), or deliver the versioned bytes (open_access_channel — Package Manager Distribution, which consumes this scheme to resolve).

Notes

The version number is a promise, and it only works if maintainers actually honor it. A single breaking change shipped as a minor does more damage than having no scheme, precisely because dependents stopped re-testing and upgraded on trust. Adopting a scheme therefore takes on an obligation — every release now asserts a compatibility claim — and a scheme you don't discipline yourself to follow is worse than an honest "re-test everything."

References

[1] Dependency hell is the familiar failure where a project's transitive dependencies impose mutually-incompatible version constraints, leaving no satisfiable set. A compatibility-encoding version scheme exists largely to make such constraints expressible and resolvable by tooling — it reduces the problem rather than eliminating it, which is why precise, honestly-applied increments matter. ↩