brandonbloom · July 19, 2025 05:44 · Jul 19, 2025 · Mar 18, 2024 · Mar 18, 2024 · Mar 17, 2024
diff --git a/StableVer.md b/StableVer.md
@@ -9,7 +9,7 @@ Version numbers have the short form:
 
 `<major>.<minor>`
 
-Breakings may only be introduced in major version bumps. However, no breaking change
+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

diff --git a/StableVer.md b/StableVer.md
@@ -13,7 +13,7 @@ Breakings may only be introduced in major version bumps. However, no breaking ch
 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
+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.
 
 ## Stability Status

diff --git a/StableVer.md b/StableVer.md
@@ -61,4 +61,5 @@ release. Bug fixes may introduce breaking changes within the _undefined_ portion
 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.
+or feature removals. This capacity should not be used to avoid providing sufficient migration
+time for deprecations.
diff --git a/StableVer.md b/StableVer.md
@@ -31,7 +31,8 @@ Unstable features fall in to five categories: **alpha**, **beta**,
 warning.
 
 **Beta** features _may_ experience breaking changes, but the goal is for them to
-stabilize, and so such breakage will be accompanied by guidance.
+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.

diff --git a/StableVer.md b/StableVer.md
@@ -33,8 +33,8 @@ 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.
+**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.

diff --git a/StableVer.md b/StableVer.md
@@ -57,4 +57,7 @@ _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.
+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.
diff --git a/StableVer.md b/StableVer.md
@@ -24,8 +24,8 @@ 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**.
+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.
@@ -39,6 +39,11 @@ 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.
+
 ## Version Numbering
 
 When the major version is 0, it is called the "alpha release". All features are
@@ -49,3 +54,7 @@ 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.
diff --git a/versioning.md → StableVer.md b/versioning.md → StableVer.md
@@ -1,12 +1,25 @@
-# Versioning
+# StableVer
 
-This project uses `$SOME_CUTE_VERSIONING_SCHEME_NAME`. It works like this:
+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>`
 
-## Stability
+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.

diff --git a/versioning.md b/versioning.md
@@ -12,7 +12,7 @@ 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**,
-**internal**, and **deprecated**.
+**deprecated**, and **internal**.
 
 **Alpha** features are subject to breaking changes at anytime and without
 warning.

diff --git a/versioning.md b/versioning.md
@@ -12,7 +12,7 @@ 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**,
-**internal**, and **"deprecated"**.
+**internal**, and **deprecated**.
 
 **Alpha** features are subject to breaking changes at anytime and without
 warning.

diff --git a/versioning.md b/versioning.md
@@ -4,9 +4,7 @@ This project uses `$SOME_CUTE_VERSIONING_SCHEME_NAME`. It works like this:
 
 Version numbers have the short form:
 
-```
-<major>.<minor>
-```
+`<major>.<minor>`
 
 ## Stability
 

diff --git a/versioning.md b/versioning.md
@@ -0,0 +1,40 @@
+# Versioning
+
+This project uses `$SOME_CUTE_VERSIONING_SCHEME_NAME`. It works like this:
+
+Version numbers have the short form:
+
+```
+<major>.<minor>
+```
+
+## Stability
+
+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**,
+**internal**, and **"deprecated"**.
+
+**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_.
No results found