diff --git a/doc/api.rst b/doc/api.rst index 85ef46ca6ba..dd1a08cf7a5 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -10,7 +10,7 @@ This page provides an auto-generated summary of xarray's API. For more details and examples, refer to the relevant chapters in the main part of the documentation. -See also: :ref:`public api` +See also: :ref:`public api` and :ref:`api stability`. Top-level functions =================== diff --git a/doc/getting-started-guide/faq.rst b/doc/getting-started-guide/faq.rst index af3b55a4086..4f5795882d9 100644 --- a/doc/getting-started-guide/faq.rst +++ b/doc/getting-started-guide/faq.rst @@ -416,6 +416,18 @@ would certainly appreciate it. We recommend two citations. url = {https://doi.org/10.5281/zenodo.59499} } +.. _api stability: + +How stable is Xarray's API? +--------------------------- + +Xarray tries very hard to maintain backwards compatibility in our :ref:`api` between released versions. +Whilst we do occasionally make breaking changes in order to improve the library, +we `signpost changes `_ with ``DeprecationWarnings`` for many releases in advance. +(An exception is bugs - whose behaviour we try to fix as soon as we notice them.) +Our `test-driven development practices `_ help to ensure any accidental regressions are caught. +This philosophy applies to everything in the `public API `_. + .. _public api: What parts of xarray are considered public API? diff --git a/doc/whats-new.rst b/doc/whats-new.rst index cbc59a708aa..48de0323318 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -54,6 +54,8 @@ Bug fixes Documentation ~~~~~~~~~~~~~ +- Clarified xarray's policy on API stability in the FAQ. (:issue:`9854`, :pull:`9855`) + By `Tom Nicholas `_. Internal Changes ~~~~~~~~~~~~~~~~