@@ -66,16 +66,19 @@ prevents unexpected breaking of code.
6666
6767Rules
6868^^^^^
69- - Deprecations are targeted at the next :ref: `meso release <pr-milestones >` (e.g. 3.x )
69+ - Deprecations are targeted at the next :ref: `meso release <pr-milestones >` (e.g. 3.Y )
7070- Deprecated API is generally removed (expired) two point-releases after introduction
7171 of the deprecation. Longer deprecations can be imposed by core developers on
7272 a case-by-case basis to give more time for the transition
7373- The old API must remain fully functional during the deprecation period
7474- If alternatives to the deprecated API exist, they should be available
7575 during the deprecation period
76+ - If the deprecation is introduced as part of implementing an alternative, then it
77+ should be marked pending.
7678- If in doubt, decisions about API changes are finally made by the
7779 `API consistency lead <https://matplotlib.org/governance/people.html >`_ developer.
7880
81+
7982.. _intro-deprecation :
8083
8184Introduce deprecation
@@ -137,6 +140,25 @@ Expire deprecation
137140 instead. For removed items that were not in the stub file, only deleting from the
138141 allowlist is required.
139142
143+ .. _pending-deprecation :
144+
145+ Pending deprecations
146+ ^^^^^^^^^^^^^^^^^^^^
147+
148+ If the deprecation is introduced as part of implementing an alternative, then the
149+ deprecation is marked as pending and introduced one meso release after the feature.
150+
151+ For example, if the feature is released in 3.Y, then code that should be deprecated
152+ because of the feature is marked with the appropriate deprecation decorator and
153+ the following settings:
154+ * the *pending * parameter is set to ``True ``
155+ * the *removal * parameter is left blank
156+
157+ Once the version with the feature (e.g. 3.Y) has been released, the pending deprecation
158+ is introduced. The decorator should be updated such that:
159+ * *pending * is set to ``False ``
160+ * *since * is set to the next meso release (3.Y+1)
161+ * *removal * is set to at least 2 versions after (3.Y+3) introduction.
140162
141163.. redirect-from :: /devel/coding_guide#new-features-and-api-changes
142164
0 commit comments