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.