This document describes the "StableVer" versioning scheme. Like SemVer and related schemes, major version numbers convey semantic information about breaking changes. Unlike SemVer, StableVer discourages breaking changes by adding semantics regarding feature stability, deprecation, and migrations.
Version numbers have the short form:
<major>.<minor>
Breaking changes may only be introduced in major version bumps. However, no breaking change may be made to a feature unless it was declared deprecated in the previous major version bump.
A key property of projects that use StableVer is that it should always be possible to migrate from major version N to major version N+1 without breaking changes -- provided that you are not using any features that were marked deprecated in version N.
Projects using StableVer are responsible for communicating the stability status of individual APIs, data formats, and other features.
Functionality can be either stable or unstable. Stable features are not subject to breaking changes, even in major version upgrades.
Unstable features fall in to five categories: alpha, beta, deprecated, internal, and undefined.
Alpha features are subject to breaking changes at anytime and without warning.
Beta features may experience breaking changes, but the goal is for them to stabilize, and so such breakage will be accompanied by guidance. It is not necessary to bump the major version when making changes to beta features.
Deprecated features are previously beta or stable features that will be removed in the next major version release. Warning and a migration plan will be provided.
Internal features are also subject to breaking changes at anytime. They differ from alpha features in that they are not expected to stabilize.
Undefined behavior of features is the subset of functionality of any feature -- include stable features -- that has not been adequately documented. Undefined behavior is treated as internal for unstable features, and as beta when associated with otherwise stable features.
When the major version is 0, it is called the "alpha release". All features are considered alpha, unless explicitly declared otherwise. Even if designated stable, functionality in an alpha release should should be treated as beta at best.
For major version 1 and up, all documented features are considered stable, unless otherwise indicated. All undocumented functionality is considered internal.
Non-breaking bug fixes and unstable features may be added or modified in any minor version release. Bug fixes may introduce breaking changes within the undefined portion of stable features, but should be accompanied by guidance.
Major version bumps may be used for marketing purposes, even if there are no new deprecations or feature removals. This capacity should not be used to avoid providing sufficient migration time for deprecations.
This versioning scheme is compelling. In particular, it codifies a more fine-grained measure of stability than semantic versioning does, with stronger assurances made for stable features. Semantic versioning could be seen as this versioning scheme with at most all features being declared beta plus a questionably useful patch version.
However, the specification is lacking some guidance in how to bump the major and minor versions. Suppose the major version is 1 or greater, so that some features are stable. Clearly these features will never undergo breaking changes. Also clearly is that deprecated features can be removed only when bumping the major version. But what is unclear is which features can be marked deprecated. Beta features would make the most sense, since the specification states that any breakage of beta features will be accompanied by guidance (which currently means, incidentally and not necessarily inconveniently, that any features designated stable during major version 0 can be removed only in major version 1).
So the major version is bumped when removing deprecated features. Should it be bumped in other situations, perhaps when making (any kind, or just large?) breaking changes to beta features? And what about minor versions? Bumped when making any other kinds of changes, including breaking changes to alpha and internal features?
Also, no mention is made about bugfixes possibly causing irremediably subjectively breaking changes in stable features. Presumably the intention is to allow bugs to be fixed, with some consideration for how breaking they are.
(For what it's worth, I like kngl's suggestion of StableVer as name for this scheme.)