Add a guide to deprecating features by Lincoln-developer · Pull Request #1469 · python/devguide

Lincoln-developer · 2024-11-08T12:29:14Z

This pull request introduces a new section in the Developer Guide to document the practical steps for deprecating features in CPython. It complements the policy guidelines outlined in PEP 387 by providing a detailed, actionable workflow for contributors

📚 Documentation preview 📚: https://cpython-devguide--1469.org.readthedocs.build/developer-workflow/cpython-deprecation-workflow/

AA-Turner

I think we can make a few improvements here specific to CPython.

A

P.S. Out of idle curiosity, did you use an LLM/GPT to help write this document? There's a couple of hallmarks I recognise, but it could just be a general style!

AA-Turner · 2024-11-08T12:53:41Z

+* **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
+     )


We should probably use warnings._deprecated() instead here

Thanks let me work on this change

AA-Turner · 2024-11-08T12:55:11Z

+------------------------------------
+Before proposing deprecation:
+
+* **Assess Usage**: Use tools like GitHub search, ``grep``, or ``PyPI statistics`` to determine the extent and context of usage.


Perhaps you could add links here?

okay sure, let me add them

Co-authored-by: Adam Turner <[email protected]>

python-cla-bot · 2025-04-18T09:56:12Z

All commit authors signed the Contributor License Agreement.

StanFromIreland · 2025-09-08T20:50:35Z

+
+Once approved:
+
+* **Raise a Warning**: Use ``warnings._deprecated`` with :exc:`DeprecationWarning` for typical cases.


Why is this preferred over the documented and more common warnings.warn (over 3x in the stdlib)?

StanFromIreland · 2025-09-08T20:50:49Z

+Workflow for Deprecating Features in CPython
+==============================================


Suggested change

Workflow for Deprecating Features in CPython

==============================================

Workflow for Deprecating Features in CPython

============================================

StanFromIreland · 2025-09-08T20:51:03Z

+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.


Please wrap lines to 79 characters.

StanFromIreland · 2025-09-08T20:51:52Z

+
+Before proposing deprecation:
+
+* **Assess Usage**: Use tools like GitHub search, `grep`_, or `PyPI statistics`_ to determine the extent and context of usage.


Maybe add a link to the GitHub search and list Victor's script: https://hugovk.dev/blog/2022/how-to-search-5000-python-projects/ ?

StanFromIreland · 2025-09-08T20:52:47Z

+Open an issue
+-------------
+
+Start by creating a GitHub issue to propose the deprecation:


I think we should recommend a thread on Discourse first?

StanFromIreland · 2025-09-08T20:55:31Z

+------------------
+
+* **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.


GitHub milestones

These are not used in CPython?

StanFromIreland · 2025-09-08T20:56:34Z

+  * Update documentation, removing references to the deprecated feature.
+  * Include the removal in the "What's New" for the release.
+
+``PendingDeprecationWarning`` workflow


This stage seems odd, how often is this done?

StanFromIreland · 2025-09-08T20:59:06Z

+------------------------
+
+* Use the ``.. deprecated-removed::`` roles for documentation.
+* Add ``See Also`` links to :pep:`387` and DevGuide for policy and process details.


I don't understand, do you suggest a .. see-also:: under every deprecated feature?

StanFromIreland · 2025-09-08T20:59:18Z

+  * No ``pending-removal-in`` entry is needed during this stage.
+
+References and templates
+------------------------


We can also link to PEP 4

StanFromIreland · 2025-09-08T20:59:47Z

   :maxdepth: 5

   communication-channels
+   cpython-deprecation-workflow


This should definitely be below development cycle

sirosen · 2026-06-21T04:30:44Z

I see that at least three people have put in effort here, but it's stalled. I can carry it forward, if that seems appropriate.

@StanFromIreland , as the most recent reviewer, what would you think of me picking this up and continuing the work in a new PR?
(I'd preserve these commits, but open a fresh PR with my additions.)

StanFromIreland · 2026-06-21T09:59:26Z

@sirosen yes, it would be great for someone to pick this up, this has been stale for a while. I would suggest that whoever does pick it up do at least one deprecation in CPython beforehand. I think part of the issue here was that current practices aren't written down, which made it easy to end up inventing new ones. If you have any questions while working on this, feel free to ask/ping me.

Other things worth covering here would be soft deprecations. I also wouldn't focus too much on the "When to deprecate?" section, that's a difficult topic and all cases can't be covered by the docs, some general guidelines would suffice. In the future we could also expand the section to cover removing the deprecated items, as this gets difficult e.g. when things are in the stable ABI.

hugovk · 2026-06-21T10:05:39Z

And might be worth starting this guide from scratch, rather than continuing from this PR.

Lincoln-developer added 2 commits November 8, 2024 15:24

Added deprecation workflow in CPython.

f2fd360

Fixed sphinx-linting error

e99387d

AA-Turner requested changes Nov 8, 2024

View reviewed changes

AA-Turner changed the title ~~gh-1419: Added deprecation workflow for CPython.~~ Add a guide to deprecating features Nov 8, 2024

AA-Turner linked an issue Nov 8, 2024 that may be closed by this pull request

Document the workflow for deprecating something in CPython. #1419

Open

Lincoln-developer and others added 8 commits November 8, 2024 16:07

Update developer-workflow/cpython-deprecation-workflow.rst

be9224b

Co-authored-by: Adam Turner <[email protected]>

Update developer-workflow/cpython-deprecation-workflow.rst

b8fbd0b

Co-authored-by: Adam Turner <[email protected]>

Update developer-workflow/cpython-deprecation-workflow.rst

207294f

Co-authored-by: Adam Turner <[email protected]>

Update developer-workflow/cpython-deprecation-workflow.rst

a90e99a

Co-authored-by: Adam Turner <[email protected]>

Update developer-workflow/cpython-deprecation-workflow.rst

fc0b4ec

Co-authored-by: Adam Turner <[email protected]>

Update developer-workflow/cpython-deprecation-workflow.rst

7029868

Co-authored-by: Adam Turner <[email protected]>

Update developer-workflow/cpython-deprecation-workflow.rst

0dc75ec

Co-authored-by: Adam Turner <[email protected]>

fixed requested changes

0d8bd61

Lincoln-developer requested a review from AA-Turner November 8, 2024 13:38

fixed required warning function

d077a58

StanFromIreland reviewed Sep 8, 2025

View reviewed changes

StanFromIreland marked this pull request as draft September 8, 2025 21:00


		Once approved:

		* Raise a Warning: Use ``warnings._deprecated`` with :exc:`DeprecationWarning` for typical cases.

		Workflow for Deprecating Features in CPython
		==============================================


		Before proposing deprecation:

		* Assess Usage: Use tools like GitHub search, `grep`_, or `PyPI statistics`_ to determine the extent and context of usage.

Uh oh!

Conversation

Lincoln-developer commented Nov 8, 2024 • edited by hugovk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AA-Turner left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

python-cla-bot Bot commented Apr 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sirosen commented Jun 21, 2026

Uh oh!

StanFromIreland commented Jun 21, 2026

Uh oh!

hugovk commented Jun 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Lincoln-developer commented Nov 8, 2024 •

edited by hugovk

Loading

python-cla-bot Bot commented Apr 18, 2025 •

edited

Loading