From f2fd360c61d67c90e550060027c391107fed2f1f Mon Sep 17 00:00:00 2001 From: Lincoln-developer Date: Fri, 8 Nov 2024 15:24:54 +0300 Subject: [PATCH 01/11] Added deprecation workflow in CPython. --- .../cpython-deprecation-workflow.rst | 80 +++++++++++++++++++ developer-workflow/index.rst | 1 + 2 files changed, 81 insertions(+) create mode 100644 developer-workflow/cpython-deprecation-workflow.rst diff --git a/developer-workflow/cpython-deprecation-workflow.rst b/developer-workflow/cpython-deprecation-workflow.rst new file mode 100644 index 0000000000..dddea52320 --- /dev/null +++ b/developer-workflow/cpython-deprecation-workflow.rst @@ -0,0 +1,80 @@ +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`. + +1. Identify Features for Deprecation +------------------------------------ +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. + +2. 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. + +3. Deprecation Implementation +----------------------------- +Once approved: + +* **Raise a Warning**: Use :func:`warnings.warn` 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.warn( + "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. + +4. 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. + +5. Plan Removal +--------------- +After the deprecation period (typically 2+ 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. + +6. 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. + +7. References and Templates +--------------------------- +* Use ``.. deprecated::`` and ``.. removed::`` Sphinx 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 e73927f1dd..b46b2107dc 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 From e99387d8f4b198c4849570e385e0f86e000c75c8 Mon Sep 17 00:00:00 2001 From: Lincoln-developer Date: Fri, 8 Nov 2024 15:50:22 +0300 Subject: [PATCH 02/11] Fixed sphinx-linting error --- developer-workflow/cpython-deprecation-workflow.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer-workflow/cpython-deprecation-workflow.rst b/developer-workflow/cpython-deprecation-workflow.rst index dddea52320..cfb87c733f 100644 --- a/developer-workflow/cpython-deprecation-workflow.rst +++ b/developer-workflow/cpython-deprecation-workflow.rst @@ -8,7 +8,7 @@ This document outlines the practical steps required for deprecating a feature, s ------------------------------------ Before proposing deprecation: -* **Assess Usage**: Use tools like GitHub search, `grep`, or PyPI statistics to determine the extent and context of usage. +* **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. 2. Open an Issue From be9224b6813b5b6f1a0b7ed8dcf186dfe182166b Mon Sep 17 00:00:00 2001 From: Lincoln <71312724+Lincoln-developer@users.noreply.github.com> Date: Fri, 8 Nov 2024 16:07:43 +0300 Subject: [PATCH 03/11] Update developer-workflow/cpython-deprecation-workflow.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- developer-workflow/cpython-deprecation-workflow.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/developer-workflow/cpython-deprecation-workflow.rst b/developer-workflow/cpython-deprecation-workflow.rst index cfb87c733f..205adcc140 100644 --- a/developer-workflow/cpython-deprecation-workflow.rst +++ b/developer-workflow/cpython-deprecation-workflow.rst @@ -4,8 +4,9 @@ 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`. -1. Identify Features for Deprecation ------------------------------------- +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. From b8fbd0b68fa14cdedd9799eb238515deece38458 Mon Sep 17 00:00:00 2001 From: Lincoln <71312724+Lincoln-developer@users.noreply.github.com> Date: Fri, 8 Nov 2024 16:09:39 +0300 Subject: [PATCH 04/11] Update developer-workflow/cpython-deprecation-workflow.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- developer-workflow/cpython-deprecation-workflow.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/developer-workflow/cpython-deprecation-workflow.rst b/developer-workflow/cpython-deprecation-workflow.rst index 205adcc140..7b10461e8c 100644 --- a/developer-workflow/cpython-deprecation-workflow.rst +++ b/developer-workflow/cpython-deprecation-workflow.rst @@ -12,8 +12,9 @@ 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. -2. Open an Issue ----------------- +Open an issue +------------- + Start by creating a GitHub issue to propose the deprecation: * Clearly describe the feature and why deprecation is needed. From 207294f77393e8f067da6964296de89a6ba35803 Mon Sep 17 00:00:00 2001 From: Lincoln <71312724+Lincoln-developer@users.noreply.github.com> Date: Fri, 8 Nov 2024 16:10:00 +0300 Subject: [PATCH 05/11] Update developer-workflow/cpython-deprecation-workflow.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- developer-workflow/cpython-deprecation-workflow.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/developer-workflow/cpython-deprecation-workflow.rst b/developer-workflow/cpython-deprecation-workflow.rst index 7b10461e8c..9ffbfb8085 100644 --- a/developer-workflow/cpython-deprecation-workflow.rst +++ b/developer-workflow/cpython-deprecation-workflow.rst @@ -20,8 +20,9 @@ Start by creating a GitHub issue to propose the deprecation: * Clearly describe the feature and why deprecation is needed. * Encourage community feedback and suggestions. -3. Deprecation Implementation ------------------------------ +Deprecation implementation +-------------------------- + Once approved: * **Raise a Warning**: Use :func:`warnings.warn` with :exc:`DeprecationWarning` for typical cases. From a90e99a6ca87a9aa68001e13bde7d5bdc9f4debf Mon Sep 17 00:00:00 2001 From: Lincoln <71312724+Lincoln-developer@users.noreply.github.com> Date: Fri, 8 Nov 2024 16:10:16 +0300 Subject: [PATCH 06/11] Update developer-workflow/cpython-deprecation-workflow.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- developer-workflow/cpython-deprecation-workflow.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/developer-workflow/cpython-deprecation-workflow.rst b/developer-workflow/cpython-deprecation-workflow.rst index 9ffbfb8085..f39225af8a 100644 --- a/developer-workflow/cpython-deprecation-workflow.rst +++ b/developer-workflow/cpython-deprecation-workflow.rst @@ -47,8 +47,9 @@ Once approved: * Include details in the "Porting" section of the "What's New" documentation. * Update the ``pending-removal-in-{version}.rst`` file with the deprecation timeline. -4. Track Deprecations ---------------------- +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. From fc0b4ec8c0630048937dcf7f300aa3f8ef538367 Mon Sep 17 00:00:00 2001 From: Lincoln <71312724+Lincoln-developer@users.noreply.github.com> Date: Fri, 8 Nov 2024 16:10:35 +0300 Subject: [PATCH 07/11] Update developer-workflow/cpython-deprecation-workflow.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- developer-workflow/cpython-deprecation-workflow.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/developer-workflow/cpython-deprecation-workflow.rst b/developer-workflow/cpython-deprecation-workflow.rst index f39225af8a..898b7f26db 100644 --- a/developer-workflow/cpython-deprecation-workflow.rst +++ b/developer-workflow/cpython-deprecation-workflow.rst @@ -64,8 +64,9 @@ After the deprecation period (typically 2+ releases): * Update documentation, removing references to the deprecated feature. * Include the removal in the "What's New" for the release. -6. PendingDeprecationWarning Workflow -------------------------------------- +``PendingDeprecationWarning`` workflow +-------------------------------------- + For gradual deprecations: * **Use Case**: When you want to signal future deprecation but not yet alert end-users. From 7029868c3b6ce58296a84b5526c0ab77907584b5 Mon Sep 17 00:00:00 2001 From: Lincoln <71312724+Lincoln-developer@users.noreply.github.com> Date: Fri, 8 Nov 2024 16:10:49 +0300 Subject: [PATCH 08/11] Update developer-workflow/cpython-deprecation-workflow.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- developer-workflow/cpython-deprecation-workflow.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/developer-workflow/cpython-deprecation-workflow.rst b/developer-workflow/cpython-deprecation-workflow.rst index 898b7f26db..4e4b1a982a 100644 --- a/developer-workflow/cpython-deprecation-workflow.rst +++ b/developer-workflow/cpython-deprecation-workflow.rst @@ -53,9 +53,10 @@ 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. -5. Plan Removal ---------------- -After the deprecation period (typically 2+ releases): +Plan removal +------------ + +After the deprecation period (not less than two releases): * Open a new issue for removal. * Follow removal steps: From 0dc75ec7d1b2c340e38c9cb127e87ff9e963da24 Mon Sep 17 00:00:00 2001 From: Lincoln <71312724+Lincoln-developer@users.noreply.github.com> Date: Fri, 8 Nov 2024 16:11:09 +0300 Subject: [PATCH 09/11] Update developer-workflow/cpython-deprecation-workflow.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- developer-workflow/cpython-deprecation-workflow.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/developer-workflow/cpython-deprecation-workflow.rst b/developer-workflow/cpython-deprecation-workflow.rst index 4e4b1a982a..43e614fdac 100644 --- a/developer-workflow/cpython-deprecation-workflow.rst +++ b/developer-workflow/cpython-deprecation-workflow.rst @@ -80,7 +80,8 @@ For gradual deprecations: * Mention the pending deprecation in “What’s New.” * No ``pending-removal-in`` entry is needed during this stage. -7. References and Templates ---------------------------- -* Use ``.. deprecated::`` and ``.. removed::`` Sphinx roles for documentation. +References and templates +------------------------ + +* Use the ``.. deprecated-removed::`` roles for documentation. * Add ``See Also`` links to :pep:`387` and DevGuide for policy and process details. From 0d8bd61afcd0fb6942723aedf6a58c3562838279 Mon Sep 17 00:00:00 2001 From: Lincoln-developer Date: Fri, 8 Nov 2024 16:26:17 +0300 Subject: [PATCH 10/11] fixed requested changes --- developer-workflow/cpython-deprecation-workflow.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/developer-workflow/cpython-deprecation-workflow.rst b/developer-workflow/cpython-deprecation-workflow.rst index 43e614fdac..fb020e8ce7 100644 --- a/developer-workflow/cpython-deprecation-workflow.rst +++ b/developer-workflow/cpython-deprecation-workflow.rst @@ -9,9 +9,12 @@ 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. +* **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 ------------- @@ -35,7 +38,7 @@ Once approved: .. code-block:: python import warnings - warnings.warn( + warnings._deprecated( "Feature X is deprecated and will be removed in Python 3.Y", DeprecationWarning, stacklevel=2 From d077a584de16c84e2a296ff18ff8a70b5d739ab2 Mon Sep 17 00:00:00 2001 From: Lincoln-developer Date: Mon, 11 Nov 2024 08:35:19 +0300 Subject: [PATCH 11/11] fixed required warning function --- developer-workflow/cpython-deprecation-workflow.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer-workflow/cpython-deprecation-workflow.rst b/developer-workflow/cpython-deprecation-workflow.rst index fb020e8ce7..cdb0f21287 100644 --- a/developer-workflow/cpython-deprecation-workflow.rst +++ b/developer-workflow/cpython-deprecation-workflow.rst @@ -28,7 +28,7 @@ Deprecation implementation Once approved: -* **Raise a Warning**: Use :func:`warnings.warn` with :exc:`DeprecationWarning` for typical cases. +* **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.