diff --git a/developer-workflow/cpython-deprecation-workflow.rst b/developer-workflow/cpython-deprecation-workflow.rst
new file mode 100644
index 000000000..cdb0f2128
--- /dev/null
+++ b/developer-workflow/cpython-deprecation-workflow.rst
@@ -0,0 +1,90 @@
+Workflow for Deprecating Features in CPython
+==============================================
+
+Deprecation in CPython is a multi-step process that involves notifying users about deprecated functionality, planning its eventual removal, and providing adequate guidance for migration.
+This document outlines the practical steps required for deprecating a feature, supplementing the policy guidelines defined in :pep:`387`.
+
+Check prevalence and consider alternatives
+------------------------------------------
+
+Before proposing deprecation:
+
+* **Assess Usage**: Use tools like GitHub search, `grep`_, or `PyPI statistics`_ to determine the extent and context of usage.
+* **Consider Alternatives**: Ensure there are suitable replacements or upgrades available.
+
+.. _grep: https://www.gnu.org/software/grep/
+.. _PyPI statistics: https://pypistats.org/
+
+Open an issue
+-------------
+
+Start by creating a GitHub issue to propose the deprecation:
+
+* Clearly describe the feature and why deprecation is needed.
+* Encourage community feedback and suggestions.
+
+Deprecation implementation
+--------------------------
+
+Once approved:
+
+* **Raise a Warning**: Use ``warnings._deprecated`` with :exc:`DeprecationWarning` for typical cases.
+ If the feature is in its early deprecation phase:
+
+ * Use :exc:`PendingDeprecationWarning` initially, which transitions to :exc:`DeprecationWarning` after a suitable period.
+
+ Example:
+
+ .. code-block:: python
+
+ import warnings
+ warnings._deprecated(
+ "Feature X is deprecated and will be removed in Python 3.Y",
+ DeprecationWarning,
+ stacklevel=2
+ )
+
+* **Update Documentation**:
+
+ * Add a deprecation note in the relevant docstrings.
+ * Include details in the "Porting" section of the "What's New" documentation.
+ * Update the ``pending-removal-in-{version}.rst`` file with the deprecation timeline.
+
+Track deprecations
+------------------
+
+* **Monitor Usage**: After the release, observe community feedback. Deprecations may remain longer than the minimum period if low maintenance overhead is expected or usage is widespread.
+* **Timeline Review**: Use GitHub milestones or specific deprecation tracking issues to manage timelines.
+
+Plan removal
+------------
+
+After the deprecation period (not less than two releases):
+
+* Open a new issue for removal.
+* Follow removal steps:
+
+ * Remove the deprecated code and warnings.
+ * Update documentation, removing references to the deprecated feature.
+ * Include the removal in the "What's New" for the release.
+
+``PendingDeprecationWarning`` workflow
+--------------------------------------
+
+For gradual deprecations:
+
+* **Use Case**: When you want to signal future deprecation but not yet alert end-users.
+* **Transition Timeline**:
+
+ * Move from :exc:`PendingDeprecationWarning` to :exc:`DeprecationWarning` after one or more releases.
+
+* **Documentation**:
+
+ * Mention the pending deprecation in “What’s New.”
+ * No ``pending-removal-in`` entry is needed during this stage.
+
+References and templates
+------------------------
+
+* Use the ``.. deprecated-removed::`` roles for documentation.
+* Add ``See Also`` links to :pep:`387` and DevGuide for policy and process details.
diff --git a/developer-workflow/index.rst b/developer-workflow/index.rst
index e73927f1d..b46b2107d 100644
--- a/developer-workflow/index.rst
+++ b/developer-workflow/index.rst
@@ -8,6 +8,7 @@ Development workflow
:maxdepth: 5
communication-channels
+ cpython-deprecation-workflow
development-cycle
stdlib
extension-modules
pFad - Phonifier reborn
Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.
Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.
Alternative Proxies:
Alternative Proxy
pFad Proxy
pFad v3 Proxy
pFad v4 Proxy