Skip to content

Backport PR #21626 on branch v3.5.x (Added the definition of Deprecation and made Deprecation Process clearer) #21651

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 1 commit into from
Nov 16, 2021
Merged

Backport PR #21626 on branch v3.5.x (Added the definition of Deprecation and made Deprecation Process clearer) #21651

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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 @@ -275,30 +275,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.
- 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