matplotlib · timhoffm · Nov 16, 2021 · Nov 13, 2021 · Nov 13, 2021 · Nov 15, 2021
diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst
@@ -285,30 +285,58 @@ Coding guidelines
 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
 --------------