From 1f52ae0e841d75e3f331f16c0f31cd06a1675e23 Mon Sep 17 00:00:00 2001 From: Tom Nicholas <35968931+TomNicholas@users.noreply.github.com> Date: Thu, 13 May 2021 12:38:18 -0400 Subject: [PATCH] Explained what a deprecation cycle is (#5289) Co-authored-by: Anderson Banihirwe Co-authored-by: Mathias Hauser --- doc/contributing.rst | 30 +++++++++++++++++++++++++++--- doc/whats-new.rst | 4 ++++ 2 files changed, 31 insertions(+), 3 deletions(-) diff --git a/doc/contributing.rst b/doc/contributing.rst index e10ceacd59f..f43fc3e312c 100644 --- a/doc/contributing.rst +++ b/doc/contributing.rst @@ -379,10 +379,34 @@ with ``git commit --no-verify``. Backwards Compatibility ~~~~~~~~~~~~~~~~~~~~~~~ -Please try to maintain backward compatibility. *xarray* has growing number of users with +Please try to maintain backwards compatibility. *xarray* has a growing number of users with lots of existing code, so don't break it if at all possible. If you think breakage is -required, clearly state why as part of the pull request. Also, be careful when changing -method signatures and add deprecation warnings where needed. +required, clearly state why as part of the pull request. + +Be especially careful when changing function and method signatures, because any change +may require a deprecation warning. For example, if your pull request means that the +argument ``old_arg`` to ``func`` is no longer valid, instead of simply raising an error if +a user passes ``old_arg``, we would instead catch it: + +.. code-block:: python + + def func(new_arg, old_arg=None): + if old_arg is not None: + from warnings import warn + + warn( + "`old_arg` has been deprecated, and in the future will raise an error." + "Please use `new_arg` from now on.", + DeprecationWarning, + ) + + # Still do what the user intended here + +This temporary check would then be removed in a subsequent version of xarray. +This process of first warning users before actually breaking their code is known as a +"deprecation cycle", and makes changes significantly easier to handle both for users +of xarray, and for developers of other libraries that depend on xarray. + .. _contributing.ci: diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 9024f0efe37..62da8bf1ea2 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -40,6 +40,10 @@ Bug fixes Documentation ~~~~~~~~~~~~~ +- Explanation of deprecation cycles and how to implement them added to contributors + guide. (:pull:`5289`) + By `Tom Nicholas `_. + Internal Changes ~~~~~~~~~~~~~~~~