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 ~~~~~~~~~~~~~~~~ pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.

Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy