matplotlib · timhoffm · Jan 22, 2025 · Dec 23, 2024
diff --git a/doc/devel/api_changes.rst b/doc/devel/api_changes.rst
@@ -62,11 +62,12 @@ team. Generally API deprecation happens in two stages:
 * **expire:** API *is* changed as described in the introduction period

 This ensures that users are notified before the change will take effect and thus
-prevents unexpected breaking of code.
+prevents unexpected breaking of code. Occasionally deprecations are marked as
+**pending**, which means that the deprecation will be introduced in a future release.

 Rules
 ^^^^^
- Deprecations are targeted at the next :ref:`meso release <pr-milestones>` (e.g. 3.x)
+- Deprecations are targeted at the next :ref:`meso release <pr-milestones>` (e.g. 3.Y)
 - Deprecated API is generally removed (expired) 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
@@ -76,12 +77,17 @@ Rules
 - If in doubt, decisions about API changes are finally made by the
  `API consistency lead <https://matplotlib.org/governance/people.html>`_ developer.

+
 .. _intro-deprecation:

 Introduce deprecation
 ^^^^^^^^^^^^^^^^^^^^^

-#. Create :ref:`deprecation notice <api_whats_new>`
+Deprecations are introduced to warn users that the API will change. The deprecation
+notice describes how the API will change. When alternatives to the deprecated API exist,
+they are also listed in the notice and decorators.
+
+#. Create a :ref:`deprecation notice <api_whats_new>`

 #. If possible, issue a `~matplotlib.MatplotlibDeprecationWarning` when the
   deprecated API is used. There are a number of helper tools for this:
@@ -117,8 +123,10 @@ Introduce deprecation

 Expire deprecation
 ^^^^^^^^^^^^^^^^^^
+The API changes described in the introduction notice are only implemented after the
+introduction period has expired.

-#. Create :ref:`deprecation announcement <api_whats_new>`. For the content,
+#. Create a :ref:`deprecation announcement <api_whats_new>`. For the content,
   you can usually copy the deprecation notice and adapt it slightly.

 #. Change the code functionality and remove any related deprecation warnings.
@@ -137,6 +145,35 @@ Expire deprecation
     instead. For removed items that were not in the stub file, only deleting from the
     allowlist is required.

+.. _pending-deprecation:
+
+Pending deprecation
+^^^^^^^^^^^^^^^^^^^
+
+A pending deprecation is an announcement that a deprecation will be introduced in the
+future. 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 developers
+time to adapt their code so that it does not raise a deprecation
+warning. This is because their users cannot act on warnings triggered by how the tools
+and libraries use Matplotlib. It's also possible to run Python in dev mode to raise
+`PendingDeprecationWarning`.
+
+To mark a deprecation as pending, set the following parameters on the appropriate
+deprecation decorator:
+* the *pending* parameter is set to ``True``
+* the *removal* parameter is left blank
+
+When converting a pending deprecation to an introduced deprecation, update the
+decorator such that:
+* *pending* is set to ``False``
+* *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 the :ref:`API change notes <api_whats_new>` in
+the same manner as introduced and expired deprecations. The notice should include
+*pending deprecation* in the title.
+

 .. redirect-from:: /devel/coding_guide#new-features-and-api-changes