change to a new version scheme (#5825)

* change to a new version scheme

fixes #5801

* Update docs/api-stability.rst

Co-authored-by: Paul Kehrer <paul.l.kehrer@gmail.com>

* line length

Co-authored-by: Paul Kehrer <paul.l.kehrer@gmail.com>

1 files changed, 38 insertions, 13 deletions

diff --git a/docs/api-stability.rst b/docs/api-stability.rst
index fd34ced0a..3822702d3 100644
--- a/docs/api-stability.rst
+++ b/docs/api-stability.rst
@@ -37,18 +37,23 @@ policy as necessary in order to resolve a security issue or harden
 Versioning
 ----------
 
-This project uses a custom versioning scheme as described below.
+Version 35.0.0+
+~~~~~~~~~~~~~~~
 
-Given a version ``cryptography X.Y.Z``,
+Beginning with release 35.0.0 ``cryptography`` uses a Firefox-inspired version
+scheme.
 
-* ``X.Y`` is a decimal number that is incremented for
-  potentially-backwards-incompatible releases.
+Given a version ``cryptography X.Y.Z``,
 
-  * This increases like a standard decimal.
-    In other words, 0.9 is the ninth release, and 1.0 is the tenth (not 0.10).
-    The dividing decimal point can effectively be ignored.
+* ``X`` indicates the major version number. This is incremented on any feature
+  release.
+* ``Y`` is always ``0``.
+* ``Z`` is an integer that is incremented for minor backward-compatible
+  releases (such as fixing security issues or correcting regressions in a major
+  release).
 
-* ``Z`` is an integer that is incremented for backward-compatible releases.
+This scheme is compatible with `SemVer`_, though many major releases will
+**not** include any backwards-incompatible changes.
 
 Deprecation
 ~~~~~~~~~~~
@@ -56,16 +61,36 @@ Deprecation
 From time to time we will want to change the behavior of an API or remove it
 entirely. In that case, here's how the process will work:
 
-* In ``cryptography X.Y`` the feature exists.
-* In ``cryptography X.Y + 0.1`` using that feature will emit a
+* In ``cryptography X.0.0`` the feature exists.
+* In ``cryptography (X + 1).0.0`` using that feature will emit a
   ``UserWarning``.
-* In ``cryptography X.Y + 0.2`` using that feature will emit a
+* In ``cryptography (X + 2).0.0`` using that feature will emit a
   ``UserWarning``.
-* In ``cryptography X.Y + 0.3`` the feature will be removed or changed.
+* In ``cryptography (X + 3).0.0`` the feature will be removed or changed.
 
 In short, code that runs without warnings will always continue to work for a
-period of two releases.
+period of two major releases.
 
 From time to time, we may decide to deprecate an API that is particularly
 widely used. In these cases, we may decide to provide an extended deprecation
 period, at our discretion.
+
+Previous Scheme
+~~~~~~~~~~~~~~~
+
+Before version 35.0.0 this project uses a custom versioning scheme as described
+below.
+
+Given a version ``cryptography X.Y.Z``,
+
+* ``X.Y`` is a decimal number that is incremented for
+  potentially-backwards-incompatible releases.
+
+  * This increases like a standard decimal.
+    In other words, 0.9 is the ninth release, and 1.0 is the tenth (not 0.10).
+    The dividing decimal point can effectively be ignored.
+
+* ``Z`` is an integer that is incremented for backward-compatible releases.
+
+
+.. _`SemVer`: https://semver.org/