Semantic Versioning

Semver is a structured practice for versioning software. In short:

• Major versions denote breaking ABI changes.
• Minor versions denote compatible ABI changes.
• Patches denote changes such as bugfixes that can be slipped in place.

Software is generally expected to always work against the same major version with the exception of major version zero. "Version zero" is reserved for software that carry no stability guarantees.

Behaviors have to continue to be supported in perpetuity until a major version change which signals a hard break is allowed. Until then behaviors can be "soft removed" so new applications cannot use it but old applications get the compatibility path.

A major version may perform a hard break. A hard break means all of the old code is removed and the codebase can "break free" from cruft. In this case a fork of the old version must be maintained in order to run old software.

A major version may choose to mask all of the old symbols. The SDK only provides the new major version while old symbols are implemented for compatibility but completely ripped so new applications cannot use it. Versioned symbols is a useful concept for this.

Stable vs Unstable Versions

Sometimes a major or minor version is used to indicate stability. For example odd minor versions may mean something is an unstable version which is still in flux. Such a dependency would best be either unused, used with a fallback to the stable, or vendored. TBD we should probably officially recommend this here since its a very common convention (ex. used by Linux kernel.)