Alex Gaynor | f5415c8 | 2013-12-24 11:00:15 -0800 | [diff] [blame] | 1 | API Stability |
| 2 | ============= |
| 3 | |
| 4 | From its first release, ``cryptography`` will have a strong API stability |
| 5 | policy. |
| 6 | |
| 7 | What does this policy cover? |
| 8 | ---------------------------- |
| 9 | |
| 10 | This policy includes any API or behavior which is documented in this |
| 11 | documentation. |
| 12 | |
| 13 | What does "stable" mean? |
| 14 | ------------------------ |
| 15 | |
| 16 | * Public APIs will not be removed or renamed without providing a compatibility |
| 17 | alias. |
| 18 | * The behavior of existing APIs will not change. |
| 19 | |
| 20 | What doesn't this policy cover? |
| 21 | ------------------------------- |
| 22 | |
| 23 | * We may add new features, things like the result of ``dir(obj))`` or the |
| 24 | contents of ``obj.__dict__`` may change. |
Alex Gaynor | d43134a | 2013-12-24 11:03:16 -0800 | [diff] [blame] | 25 | * Objects are not guaranteed to be pickleable, and pickled objects from one |
Alex Gaynor | f5415c8 | 2013-12-24 11:00:15 -0800 | [diff] [blame] | 26 | version of ``cryptography`` may not be loadable in future versions. |
Alex Gaynor | 6cf1e69 | 2013-12-24 11:02:54 -0800 | [diff] [blame] | 27 | * Development versions of ``cryptography``. Before a feature is in a release, |
| 28 | it is not covered by this policy and may change. |
Alex Gaynor | f5415c8 | 2013-12-24 11:00:15 -0800 | [diff] [blame] | 29 | |
| 30 | Security |
| 31 | ~~~~~~~~ |
| 32 | |
Alex Gaynor | 1c9e57b | 2013-12-24 12:47:45 -0800 | [diff] [blame] | 33 | One exception to our API stability policy is for security. We will violate this |
| 34 | policy as necessary in order to resolve a security issue or harden |
| 35 | ``cryptography`` against a possible attack. |
Alex Gaynor | f5415c8 | 2013-12-24 11:00:15 -0800 | [diff] [blame] | 36 | |
| 37 | Deprecation |
| 38 | ----------- |
| 39 | |
| 40 | From time to time we will want to change the behavior of an API or remove it |
| 41 | entirely. In that case, here's how the process will work: |
| 42 | |
| 43 | * In ``cryptography X.Y`` the feature exists. |
| 44 | * In ``cryptography X.Y+1`` using that feature will emit a |
| 45 | ``PendingDeprecationWarning``. |
| 46 | * In ``cryptography X.Y+2`` using that feature will emit a |
| 47 | ``DeprecationWarning``. |
| 48 | * In ``cryptography X.Y+3`` the feature will be removed or changed. |
| 49 | |
| 50 | In short, code which runs without warnings will always continue to work for a |
| 51 | period of two releases. |