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 000000000..dddea5232 --- /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 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 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 dddea5232..cfb87c733 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 cfb87c733..205adcc14 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 205adcc14..7b10461e8 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 7b10461e8..9ffbfb808 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 9ffbfb808..f39225af8 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 f39225af8..898b7f26d 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 898b7f26d..4e4b1a982 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 4e4b1a982..43e614fda 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 43e614fda..fb020e8ce 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 fb020e8ce..cdb0f2128 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. 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