diff options
| -rw-r--r-- | docs/api-stability.rst | 51 | ||||
| -rw-r--r-- | docs/contributing.rst | 1 | ||||
| -rw-r--r-- | docs/index.rst | 1 |
3 files changed, 52 insertions, 1 deletions
diff --git a/docs/api-stability.rst b/docs/api-stability.rst new file mode 100644 index 00000000..e87cc140 --- /dev/null +++ b/docs/api-stability.rst @@ -0,0 +1,51 @@ +API Stability +============= + +From its first release, ``cryptography`` will have a strong API stability +policy. + +What does this policy cover? +---------------------------- + +This policy includes any API or behavior which is documented in this +documentation. + +What does "stable" mean? +------------------------ + +* Public APIs will not be removed or renamed without providing a compatibility + alias. +* The behavior of existing APIs will not change. + +What doesn't this policy cover? +------------------------------- + +* We may add new features, things like the result of ``dir(obj))`` or the + contents of ``obj.__dict__`` may change. +* Objects are not guaranteed to be pickleable, and pickled objects from one + version of ``cryptography`` may not be loadable in future versions. +* Development versions of ``cryptography``. Before a feature is in a release, + it is not covered by this policy and may change. + +Security +~~~~~~~~ + +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. + +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 + ``PendingDeprecationWarning``. +* In ``cryptography X.Y+2`` using that feature will emit a + ``DeprecationWarning``. +* In ``cryptography X.Y+3`` the feature will be removed or changed. + +In short, code which runs without warnings will always continue to work for a +period of two releases. diff --git a/docs/contributing.rst b/docs/contributing.rst index 744f2098..620e1b6a 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -136,7 +136,6 @@ Include a space after commas between parameters: // Bad long f(int,char *) - Documentation ------------- diff --git a/docs/index.rst b/docs/index.rst index 381063df..70558bda 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -75,4 +75,5 @@ The ``cryptography`` open source project contributing security + api-stability community |