Skip to content

Added the definition of Deprecation and made Deprecation Process clearer #21626

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.

Sign up for GitHub

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

Merged
merged 6 commits into from Nov 16, 2021
Merged

Added the definition of Deprecation and made Deprecation Process clearer #21626

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
92ee55d
Added the definition of Deprecation and made Deprecation Process clearer
Nov 13, 2021
7a67b78
Update contributing.rst
Nov 13, 2021
2625d32
Update doc/devel/contributing.rst
Nov 15, 2021
88fadaa
Update doc/devel/contributing.rst
Nov 15, 2021
3a134aa
Update contributing.rst
Nov 15, 2021
3622b7c
Update contributing.rst
Nov 15, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 52 additions & 24 deletions doc/devel/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -285,30 +285,58 @@ Coding guidelines
API changes
-----------

Changes to the public API must follow a standard deprecation procedure to
prevent unexpected breaking of code that uses Matplotlib.

- Deprecations must be announced via a new file in
a new file in :file:`doc/api/next_api_changes/deprecations/` with
naming convention ``99999-ABC.rst`` where ``99999`` is the pull request
number and ``ABC`` are the contributor's initials.
- Deprecations are targeted at the next point-release (i.e. 3.x.0).
- The deprecated API should, to the maximum extent possible, remain fully
functional during the deprecation period. In cases where this is not
possible, the deprecation must never make a given piece of code do something
different than it was before; at least an exception should be raised.
Copy link
Contributor

Choose a reason for hiding this comment

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

I think this point ("must never make a given piece of code...") is important and must be kept (possibly reworded).

Copy link
Author

Choose a reason for hiding this comment

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

@jklymak @timhoffm Do you feel the same way regarding this statement? I think @timhoffm consciously changed that part to make it clear that the old API must (not should) remain functional. Therefore, any ",but..." clause is irrelevant. BTW, this is not my definite opinion, I am just paraphrasing what I think @timhoffm said and I can follow this logic. If it MUST stay functional than we don't need to worry about the "what if it does'nt remain functional" case

Copy link
Member

Choose a reason for hiding this comment

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

I'm fine with the more stringent statement to keep things simple and as a guide to contributors.

Very occasionally, this list of rules ends up being bypassed. Since this basically has to be done by the lead devs, listing the caveats and how to mitigate them seems unnecessary in a document like this. However, if I were writing the first sentence of the second paragraph I would say

API changes in Matplotlib have to be performed following the deprecation process below, except in very rare circumstances as deemed necessary by the development team.

That makes it clear we can't always live up to the ideals of this process...

Copy link
Contributor

Choose a reason for hiding this comment

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

I'm OK with @jklymak's take on this.

Copy link
Author

Choose a reason for hiding this comment

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

Alright, sounds like a good compromise

- If possible, usage of an deprecated API should emit a
`.MatplotlibDeprecationWarning`. There are a number of helper tools for this:

- Use ``_api.warn_deprecated()`` for general deprecation warnings.
- Use the decorator ``@_api.deprecated`` to deprecate classes, functions,
methods, or properties.
- To warn on changes of the function signature, use the decorators
``@_api.delete_parameter``, ``@_api.rename_parameter``, and
``@_api.make_keyword_only``.

- Deprecated API may be removed two point-releases after they were deprecated.

API consistency and stability are of great value. Therefore, API changes
(e.g. signature changes, behavior changes, removals) will only be conducted
if the added benefit is worth the user effort for adapting.

API changes in Matplotlib have to be performed following the deprecation process
below, except in very rare circumstances as deemed necessary by the development team.
This ensures that users are notified before the change will take effect and thus
prevents unexpected breaking of code.

Rules
~~~~~

- Deprecations are targeted at the next point.release (e.g. 3.x)
- Deprecated API is generally removed two two point-releases after introduction
of the deprecation. Longer deprecations can be imposed by core developers on
a case-by-case basis to give more time for the transition
- The old API must remain fully functional during the deprecation period
- If alternatives to the deprecated API exist, they should be available
during the deprecation period
- If in doubt, decisions about API changes are finally made by the
API consistency lead developer

Introducing
~~~~~~~~~~~

1. Announce the deprecation in a new file
:file:`doc/api/next_api_changes/deprecations/99999-ABC.rst` where ``99999``
is the pull request number and ``ABC`` are the contributor's initials.
2. If possible, issue a `.MatplotlibDeprecationWarning` when the deprecated
API is used. There are a number of helper tools for this:

- Use ``_api.warn_deprecated()`` for general deprecation warnings
- Use the decorator ``@_api.deprecated`` to deprecate classes, functions,
methods, or properties
- To warn on changes of the function signature, use the decorators
``@_api.delete_parameter``, ``@_api.rename_parameter``, and
``@_api.make_keyword_only``

All these helpers take a first parameter *since*, which should be set to
the next point release, e.g. "3.x".

Expiring
~~~~~~~~

1. Announce the API changes in a new file
:file:`doc/api/next_api_changes/[kind]/99999-ABC.rst` where ``99999``
is the pull request number and ``ABC`` are the contributor's initials, and
``[kind]`` is one of the folders :file:`behavior`, :file:`development`,
:file:`removals`. See :file:`doc/api/next_api_changes/README.rst` for more
information. For the content, you can usually copy the deprecation notice
and adapt it slightly.
2. Change the code functionality and remove any related deprecation warnings.

Adding new API
--------------
Expand Down