Platform Semantic Versioning and Release Train¶

Protocol — instantiates Platform Core / Extension Design

A version-numbering scheme plus a fixed release cadence that make platform change predictable — the number tells builders what a release will break, and the train tells them when it will arrive.

A platform that changes without warning is a platform builders cannot rely on. Platform Semantic Versioning and Release Train is the protocol that makes change predictable: a compatibility-signaling version scheme (major / minor / patch) coupled to a scheduled release cadence so the core and its extensions can coordinate. Its defining move is that the version number is a promise — a major bump grants permission to break, a minor says "safe to adopt," a patch says "fix only" — and the train turns when change arrives from a surprise into a calendar. It sets the rules and the schedule of change; it does not perform the migrations those rules imply, and it does not certify individual extensions.

Example¶

A mobile OS platform ships its extension SDK on an annual release train, with API-level versioning and semantic version numbers on the SDK itself. Builders read the signal directly: SDK 5.x moving to 6.0 says breaking changes are concentrated at that major boundary and nowhere else, while the annual train tells them a year in advance when a new API level lands and when the previous one's support window closes. A behavior that genuinely must change ships as 7.0 — never smuggled into 6.4 as a "minor." Because the number and the calendar both mean what they say, a complementor can plan a year of work around them instead of firefighting surprise breakage, and a security fix still reaches everyone through a defined emergency path that sits outside the train without eroding it.

How it works¶

What distinguishes the protocol from the tooling and gates around it:

Strict version semantics — major means breaking, minor means additive-and-safe, patch means fix; the mapping is enforced, not aspirational.
A scheduled cadence — releases arrive on a known rhythm with published support windows and advance deprecation notice, so builders plan rather than react.
Breakage concentrated honestly — routine breaking change is confined to major boundaries and never relabeled to look compatible.
A guarded exception path — emergency and security releases can bypass the train, but by a defined route that preserves the train's predictability.

Tuning parameters¶

Cadence — frequent fast trains versus slow LTS-style releases. Faster ships value sooner but forces builders to move more often; slower is stable but risks ossifying the platform.
Support-window length — how long each old major is maintained. Longer eases dependents but raises the operator's carrying cost.
Breaking-change budget — how much breakage a major may carry and how often majors occur.
Deprecation notice period — the lead time between "deprecated" and "removed."
Exception path — how emergency releases bypass the schedule without teaching builders that the schedule is negotiable.

When it helps, and when it misleads¶

Its strength is that it converts change from ambush into contract: builders get a signal they can plan around and breakage arrives at honest, predictable boundaries instead of at random.

Its failure modes all trace to the promise being broken. A version number that lies — a "minor" that actually breaks callers — destroys the entire signal, because the whole value was that the number could be trusted. And even a scrupulous, spec-correct change can break someone, because builders inevitably come to depend on observed behavior beyond the documented contract — Hyrum's Law.^[1] The classic misuse is relabeling a breaking change as a minor or patch to dodge a major bump, avoid a support-window reset, or keep a metric green. The discipline is to treat the version number as a binding compatibility promise, verified against the conformance policy, and to reserve the exception path for genuine emergencies.

How it implements the components¶

platform_versioning_deprecation_and_migration_policy — it supplies the version semantics, support windows, deprecation notice, and release cadence that make platform change predictable.
platform_compatibility_and_conformance_policy — the version number is a compatibility declaration: it states what a release preserves versus breaks, the promise that conformance evidence then verifies.

It sets the rules and the calendar but does not perform the migrations or deprecations it schedules — that is Platform Migration and Deprecation Tooling. It does not generate the conformance evidence that backs its promise (Platform Conformance Test Suite) or hold the authority to approve a breaking change (Platform Ecosystem Change Council).

Instantiates: Platform Core / Extension Design — the versioning protocol is what makes platform evolution predictable to builders.
Sibling mechanisms: Platform Migration and Deprecation Tooling · Platform Conformance Test Suite · Platform Ecosystem Change Council · Platform Plugin and Extension Registry · Platform API and SDK · Platform Architecture Blueprint · Platform Capability Catalog and Portal · Platform Extension Manifest · Platform Extension Review and Certification · Platform Reference Implementation · Platform Sandbox and Capability Permissions · Platform Extension Health and Dependency Dashboard

Notes¶

Versioning is a promise, not an enforcement: the number only means something if breaking changes are actually confined to majors and independently verified. The promise is kept by the Conformance Test Suite that checks it and delivered by Migration and Deprecation Tooling that carries dependents across each major boundary — the release train schedules the change but relies on both to make the schedule honest.

References¶

[1] Hyrum's Law — "with a sufficient number of users, every observable behavior of your system will be depended on by somebody" — is why even a compatible-by-spec change can break a real consumer, and why versioning must be paired with conformance evidence and migration tooling rather than trusted to signal alone. ↩