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>

CHANGELOG.rst

@@ -1,10 +1,10 @@
 Changelog
 =========
 
-.. _v3-5:
+.. _v35-0-0:
 
-3.5 - `main`_
-~~~~~~~~~~~~~
+35.0.0 - `main`_
+~~~~~~~~~~~~~~~~
 
  .. note:: This version is not yet released and is under active development.
 

docs/api-stability.rst

@@ -37,7 +37,49 @@ 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+
+~~~~~~~~~~~~~~~
+
+Beginning with release 35.0.0 ``cryptography`` uses a Firefox-inspired version
+scheme.
+
+Given a version ``cryptography X.Y.Z``,
+
+* ``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).
+
+This scheme is compatible with `SemVer`_, though many major releases will
+**not** include any backwards-incompatible changes.
+
+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.0.0`` the feature exists.
+* In ``cryptography (X + 1).0.0`` using that feature will emit a
+  ``UserWarning``.
+* In ``cryptography (X + 2).0.0`` using that feature will emit a
+  ``UserWarning``.
+* 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 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``,
 
@@ -50,22 +92,5 @@ Given a version ``cryptography X.Y.Z``,
 
 * ``Z`` is an integer that is incremented for backward-compatible releases.
 
-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
-  ``UserWarning``.
-* In ``cryptography X.Y + 0.2`` using that feature will emit a
-  ``UserWarning``.
-* In ``cryptography X.Y + 0.3`` 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.
-
-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.
+.. _`SemVer`: https://semver.org/

src/cryptography/__about__.py

@@ -21,7 +21,7 @@ __summary__ = (
 )
 __uri__ = "https://github.com/pyca/cryptography"
 
-__version__ = "3.5.dev1"
+__version__ = "35.0.0.dev1"
 
 __author__ = "The Python Cryptographic Authority and individual contributors"
 __email__ = "cryptography-dev@python.org"

vectors/cryptography_vectors/__about__.py

@@ -18,7 +18,7 @@ __summary__ = "Test vectors for the cryptography package."
 
 __uri__ = "https://github.com/pyca/cryptography"
 
-__version__ = "3.5.dev1"
+__version__ = "35.0.0.dev1"
 
 __author__ = "The Python Cryptographic Authority and individual contributors"
 __email__ = "cryptography-dev@python.org"