diff options
author | David Tucker <david@tucker.name> | 2018-01-07 08:32:36 -0800 |
---|---|---|
committer | Paul Kehrer <paul.l.kehrer@gmail.com> | 2018-01-07 10:32:36 -0600 |
commit | 038146fdc7a515937398f226531ef15d2674b3b9 (patch) | |
tree | bcc8e1e5678924473063ad345b76eda71cc2f9e9 | |
parent | 15cc998c1f60880b6177c506d89f3349201d765b (diff) | |
download | cryptography-038146fdc7a515937398f226531ef15d2674b3b9.tar.gz cryptography-038146fdc7a515937398f226531ef15d2674b3b9.tar.bz2 cryptography-038146fdc7a515937398f226531ef15d2674b3b9.zip |
Add a Versioning section to the API stability docs (#4027)
-rw-r--r-- | docs/api-stability.rst | 24 | ||||
-rw-r--r-- | docs/spelling_wordlist.txt | 1 |
2 files changed, 21 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. diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 4cf31f53..883edd17 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -100,6 +100,7 @@ unpadding verifier Verifier Verisign +versioning wildcard WoSign Xcode |