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