aboutsummaryrefslogtreecommitdiffstats
path: root/docs/api-stability.rst
diff options
context:
space:
mode:
authorDavid Tucker <david@tucker.name>2018-01-07 08:32:36 -0800
committerPaul Kehrer <paul.l.kehrer@gmail.com>2018-01-07 10:32:36 -0600
commit038146fdc7a515937398f226531ef15d2674b3b9 (patch)
treebcc8e1e5678924473063ad345b76eda71cc2f9e9 /docs/api-stability.rst
parent15cc998c1f60880b6177c506d89f3349201d765b (diff)
downloadcryptography-038146fdc7a515937398f226531ef15d2674b3b9.tar.gz
cryptography-038146fdc7a515937398f226531ef15d2674b3b9.tar.bz2
cryptography-038146fdc7a515937398f226531ef15d2674b3b9.zip
Add a Versioning section to the API stability docs (#4027)
Diffstat (limited to 'docs/api-stability.rst')
-rw-r--r--docs/api-stability.rst24
1 files changed, 20 insertions, 4 deletions
diff --git a/docs/api-stability.rst b/docs/api-stability.rst
index 2bb53841..205b1844 100644
--- a/docs/api-stability.rst
+++ b/docs/api-stability.rst
@@ -34,18 +34,34 @@ One exception to our API stability policy is for security. We will violate this
policy as necessary in order to resolve a security issue or harden
``cryptography`` against a possible attack.
+Versioning
+----------
+
+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.
+
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+1`` using that feature will emit a
+* In ``cryptography X.Y + 0.1`` using that feature will emit a
``UserWarning``.
-* In ``cryptography X.Y+2`` using that feature will emit a
+* In ``cryptography X.Y + 0.2`` using that feature will emit a
``UserWarning``.
-* In ``cryptography X.Y+3`` the feature will be removed or changed.
+* 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.