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