document pending deprecation procedure

story645 · rcomer · story645 · commit 1b37fdf8be1e · 2024-12-22T20:04:31.000-05:00
Co-authored-by: Ruth Comer &lt;10599679+rcomer@users.noreply.github.com&gt;
diff --git a/doc/devel/api_changes.rst b/doc/devel/api_changes.rst
@@ -66,16 +66,19 @@ prevents unexpected breaking of code.
 
 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
 - 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 the deprecation is introduced as part of implementing an alternative, then it
+  should be marked pending.
 - 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
@@ -137,6 +140,25 @@ Expire deprecation
      instead. For removed items that were not in the stub file, only deleting from the
      allowlist is required.
 
+.. _pending-deprecation:
+
+Pending deprecations
+^^^^^^^^^^^^^^^^^^^^
+
+If the deprecation is introduced as part of implementing an alternative, then the
+deprecation is marked as pending and introduced one meso release after the feature.
+
+For example, if the feature is released in 3.Y, then code that should be deprecated
+because of the feature is marked with the appropriate deprecation decorator and
+the following settings:
+* the *pending* parameter is set to ``True``
+* the *removal* parameter is left blank
+
+Once the version with the feature (e.g. 3.Y) has been released, the pending deprecation
+is introduced. The decorator should be updated 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 versions after (3.Y+3) introduction.
 
 .. redirect-from:: /devel/coding_guide#new-features-and-api-changes
 
