Rules#

• Deprecations are targeted at the nextmeso release (e.g. 3.Y)

• Deprecated API is generally removed (expired) two point-releases after introductionof the deprecation. Longer deprecations can be imposed by core developers ona 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 availableduring the deprecation period

• If in doubt, decisions about API changes are finally made by theAPI consistency lead developer.

Introduce deprecation#

Deprecations are introduced to warn users that the API will change. The deprecationnotice describes how the API will change. When alternatives to the deprecated API exist,they are also listed in the notice and decorators.

1. Create adeprecation notice

2. If possible, issue aMatplotlibDeprecationWarning when thedeprecated 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

   • Use@_api.deprecate_privatize_attribute to annotate deprecation ofattributes while keeping the internal private version.

   • 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 parametersince, which should be set tothe next point release, e.g. "3.x".

   You can use standard rst cross references inalternative.

3. Make appropriate changes to the type hints in the associated.pyi file.The general guideline is to match runtime reported behavior.

   • Items marked with@_api.deprecated or@_api.deprecate_privatize_attributeare generally kept during the expiry period, and thus no changes are needed onintroduction.

   • Items decorated with@_api.rename_parameter or@_api.make_keyword_onlyreport thenew (post deprecation) signature at runtime, and thusshould beupdated on introduction.

   • Items decorated with@_api.delete_parameter should include a default value hintfor the deleted parameter, even if it did not previously have one (e.g.param:<type>=...).

Expire deprecation#

The API changes described in the introduction notice are only implemented after theintroduction period has expired.

1. Create adeprecation announcement. 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.

3. Make appropriate changes to the type hints in the associated.pyi file.

   • Items marked with@_api.deprecated or@_api.deprecate_privatize_attributeare to be removed on expiry.

   • Items decorated with@_api.rename_parameter or@_api.make_keyword_onlywill have been updated at introduction, and require no change now.

   • Items decorated with@_api.delete_parameter will need to be updated to thefinal signature, in the same way as the.py file signature is updated.

   • Any entries inci/mypy-stubtest-allowlist.txt which indicate a deprecationversion should be double checked. In most cases this is not needed, though someitems were never type hinted in the first place and were added to this fileinstead. For removed items that were not in the stub file, only deleting from theallowlist is required.

Pending deprecation#

A pending deprecation is an announcement that a deprecation will be introduced in thefuture. By default, pending deprecations do not raise a warning to the user; however,pending deprecations are rendered in the documentation and listed in the release notes.Pending notices are primarily intended to give downstream library and tool developerstime to adapt their code so that it does not raise a deprecationwarning. This is because their users cannot act on warnings triggered by how the toolsand libraries use Matplotlib. It's also possible to run Python in dev mode to raisePendingDeprecationWarning.

To mark a deprecation as pending, set the following parameters on the appropriatedeprecation decorator:* thepending parameter is set toTrue* theremoval parameter is left blank

When converting a pending deprecation to an introduced deprecation, update thedecorator such that:*pending is set toFalse*since is set to the next meso release (3.Y+1)*removal is set to at least 2 meso releases after (3.Y+3) introduction.

Pending deprecations are documented in theAPI change notes inthe same manner as introduced and expired deprecations. The notice should includepending deprecation in the title.

Versioning directives#

When making a backward incompatible change, please add a versioning directive inthe docstring. The directives should be placed at the end of a description block.For example:

classFoo:"""    This is the summary.    Followed by a longer description block.    Consisting of multiple lines and paragraphs.    .. versionadded:: 3.5    Parameters    ----------    a : int        The first parameter.    b: bool, default: False        This was added later.        .. versionadded:: 3.6    """defset_b(b):"""        Set b.        .. versionadded:: 3.6        Parameters        ----------        b: bool

For classes and functions, the directive should be placed before theParameters section. For parameters, the directive should be placed at theend of the parameter description. The micro release version is omitted andthe directive should not be added to entire modules.

Release notes#

For both change notes and what's new, please avoid using cross-references in sectiontitles as it causes links to be confusing in the table of contents. Instead, ensure thata cross-reference is included in the descriptive text.

Locators~~~~~~~~The unused `Locator.autoscale()` method is deprecated (pass the axislimits to `Locator.view_limits()` instead).

Sectiontitleforfeature-------------------------Adescriptionofthefeaturefromtheuserperspective.Thisshouldincludewhatthefeatureallowsuserstodoandhowthefeatureisused.Technicaldetailsshouldbeleftoutwhentheydonotimpactusage,forexampleimplementationdetails.Thedescriptionmayincludeaashortinstructiveexample,ifithelpstounderstandthefeature.