diff --git a/doc/api.rst b/doc/api.rst index f731ac1c59a..84b272e847d 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..670510c826f 100644 --- a/doc/getting-started-guide/faq.rst +++ b/doc/getting-started-guide/faq.rst @@ -416,7 +416,19 @@ would certainly appreciate it. We recommend two citations. url = {https://doi.org/10.5281/zenodo.59499} } -.. _public api: +.. _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 `_ helps 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 c76f3800f2b..191b4a0f549 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -113,6 +113,8 @@ Documentation ~~~~~~~~~~~~~ - A chapter on :ref:`internals.timecoding` is added to the internal section (:pull:`9618`). By `Kai Mühlbauer `_. +- Clarified xarray's policy on API stability in the FAQ. (:issue:`9854`, :pull:`9855`) + By `Tom Nicholas `_. Internal Changes ~~~~~~~~~~~~~~~~