# StableVer

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>`

Breakings 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 breakign changes -- provided that
you are not using any features that were marked deprecated in version N.

## Stability Status

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 four categories: **alpha**, **beta**,
**deprecated**, and **internal**.

**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.

**Deprecated** features 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.

## Version Numbering

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_.