api-stability.rst 1.6 KB

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