Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork931
Add a guide to deprecating features#1469
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
base:main
Are you sure you want to change the base?
Uh oh!
There was an error while loading.Please reload this page.
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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!
| * **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 | ||
| ) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
We should probably usewarnings._deprecated() instead here
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Thanks let me work on this change
Uh oh!
There was an error while loading.Please reload this page.
| ------------------------------------ | ||
| Before proposing deprecation: | ||
| * **Assess Usage**: Use tools like GitHub search, ``grep``, or ``PyPI statistics`` to determine the extent and context of usage. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Perhaps you could add links here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
okay sure, let me add them
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
python-cla-botbot commentedApr 18, 2025 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
All commit authors signed the Contributor License Agreement. |
| Once approved: | ||
| * **Raise a Warning**: Use ``warnings._deprecated`` with:exc:`DeprecationWarning` for typical cases. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Why is this preferred over the documented and more commonwarnings.warn (over 3x in the stdlib)?
| Workflow for Deprecating Features in CPython | ||
| ============================================== |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| Workflow for Deprecating Features in CPython | |
| ============================================== | |
| Workflow for Deprecating Features in CPython | |
| ============================================ |
| 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Please wrap lines to 79 characters.
| Before proposing deprecation: | ||
| * **Assess Usage**: Use tools like GitHub search, `grep`_, or `PyPI statistics`_ to determine the extent and context of usage. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Maybe add a link to the GitHub search and list Victor's script:https://hugovk.dev/blog/2022/how-to-search-5000-python-projects/ ?
| Open an issue | ||
| ------------- | ||
| Start by creating a GitHub issue to propose the deprecation: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I think we should recommend a thread on Discourse first?
| ------------------ | ||
| * **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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
GitHub milestones
These are not used in CPython?
| * Update documentation, removing references to the deprecated feature. | ||
| * Include the removal in the "What's New" for the release. | ||
| ``PendingDeprecationWarning`` workflow |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
This stage seems odd, how often is this done?
| ------------------------ | ||
| * Use the ``.. deprecated-removed::`` roles for documentation. | ||
| * Add ``See Also`` links to:pep:`387` and DevGuide for policy and process details. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I don't understand, do you suggest a.. see-also:: under every deprecated feature?
| * No ``pending-removal-in`` entry is needed during this stage. | ||
| References and templates | ||
| ------------------------ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
We can also link to PEP 4
| :maxdepth:5 | ||
| communication-channels | ||
| cpython-deprecation-workflow |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
This should definitely be belowdevelopment cycle
Uh oh!
There was an error while loading.Please reload this page.
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 inPEP 387 by providing a detailed, actionable workflow for contributors
📚 Documentation preview 📚:https://cpython-devguide--1469.org.readthedocs.build/developer-workflow/cpython-deprecation-workflow/