Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Explained what a deprecation cycle is #5289

Merged
merged 9 commits into from
May 13, 2021
Merged
27 changes: 24 additions & 3 deletions doc/contributing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -379,10 +379,31 @@ 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:

def func(new_arg, old_arg=None):
dcherian marked this conversation as resolved.
Show resolved Hide resolved
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."
)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

shouldn't we also specify the warning? I'd say DeprecationWarning, but the docs are not really clear on this: it says the target audience for FutureWarning is the users of an application, which I assume is not what we want.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've synthesized the difference as FutureWarning is for behavior changes, and DeprecationWarning is for removal. I'm still not confident that's exactly right!

But DeprecationWarning is right here I think

Copy link
Collaborator

@keewis keewis May 12, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm still not confident that's exactly right!

according to the docs (immediately below the table), that was the case before python=3.7. I don't think that explanation of the difference is particularly easy to understand, though.

Since xarray is not a application, should we always use 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:

Expand Down