From 01e75181ee904282e656ee01180c2d1d3e679239 Mon Sep 17 00:00:00 2001 From: TomNicholas Date: Thu, 24 Oct 2024 17:48:00 -0400 Subject: [PATCH 1/6] new blank whatsnew --- doc/whats-new.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 9a451a836ad..18fae4e0151 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -14,6 +14,34 @@ What's New np.random.seed(123456) +.. _whats-new.2024.10.1: + +v.2024.10.1 (unreleased) +------------------------ + +New Features +~~~~~~~~~~~~ + + +Breaking changes +~~~~~~~~~~~~~~~~ + + +Deprecations +~~~~~~~~~~~~ + + +Bug fixes +~~~~~~~~~ + + +Documentation +~~~~~~~~~~~~~ + + +Internal Changes +~~~~~~~~~~~~~~~~ + .. _whats-new.2024.10.0: v2024.10.0 (Oct 24th, 2024) From aa6060259b2a8ac31df009d51dd0cafe419c2161 Mon Sep 17 00:00:00 2001 From: TomNicholas Date: Wed, 4 Dec 2024 14:56:32 -0500 Subject: [PATCH 2/6] FAQ answer on API stability --- doc/getting-started-guide/faq.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doc/getting-started-guide/faq.rst b/doc/getting-started-guide/faq.rst index af3b55a4086..482dfb76084 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 try to `signpost changes `_ with ``DeprecationWarnings`` for many months 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? From 2e2857e28401356cff9e1caab606b6e33a4735aa Mon Sep 17 00:00:00 2001 From: TomNicholas Date: Wed, 4 Dec 2024 14:56:42 -0500 Subject: [PATCH 3/6] link from API docs page --- doc/api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 =================== From ae0275b66de9507fcebf8e0e5992fff54b54ccdc Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 4 Dec 2024 19:58:36 +0000 Subject: [PATCH 4/6] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- doc/getting-started-guide/faq.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/getting-started-guide/faq.rst b/doc/getting-started-guide/faq.rst index 482dfb76084..0b694085804 100644 --- a/doc/getting-started-guide/faq.rst +++ b/doc/getting-started-guide/faq.rst @@ -421,11 +421,11 @@ would certainly appreciate it. We recommend two citations. 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 try to `signpost changes `_ with ``DeprecationWarnings`` for many months 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. +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 try to `signpost changes `_ with ``DeprecationWarnings`` for many months 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: From 330bfdb7e81c24b75cd5ef21a59438a7fdd10188 Mon Sep 17 00:00:00 2001 From: TomNicholas Date: Wed, 4 Dec 2024 14:59:31 -0500 Subject: [PATCH 5/6] whatsnew --- doc/whats-new.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 9a8154d3791..409f5ceeb06 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -44,6 +44,8 @@ Bug fixes Documentation ~~~~~~~~~~~~~ +- Clarified xarray's policy on API stability in the FAQ. (:issue:`9854`, :pull:`9855`) + By `Tom Nicholas `_. Internal Changes ~~~~~~~~~~~~~~~~ From 9fcfad426fcafd138a054e65a37707bf1960b75d Mon Sep 17 00:00:00 2001 From: Tom Nicholas Date: Wed, 4 Dec 2024 20:52:04 -0700 Subject: [PATCH 6/6] Update doc/getting-started-guide/faq.rst Co-authored-by: Maximilian Roos <5635139+max-sixty@users.noreply.github.com> --- doc/getting-started-guide/faq.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/getting-started-guide/faq.rst b/doc/getting-started-guide/faq.rst index 0b694085804..4f5795882d9 100644 --- a/doc/getting-started-guide/faq.rst +++ b/doc/getting-started-guide/faq.rst @@ -423,7 +423,7 @@ 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 try to `signpost changes `_ with ``DeprecationWarnings`` for many months in advance. +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 `_.