diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 96ffd93b6b18..287d04fa2fe0 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -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 --------------