Add a guide to deprecating features#1469
Add a guide to deprecating features#1469Lincoln-developer wants to merge 11 commits intopython:mainfrom
Conversation
AA-Turner
left a comment
AA-Turner
left a comment
There was a problem hiding this comment.
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.
We should probably use warnings._deprecated() instead here
There was a problem hiding this comment.
Thanks let me work on this change
| ------------------------------------ | ||
| 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.
Perhaps you could add links here?
There was a problem hiding this comment.
okay sure, let me add them
AA-Turner
changed the title
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>
|
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.
Why is this preferred over the documented and more common warnings.warn (over 3x in the stdlib)?
| Workflow for Deprecating Features in CPython | ||
| ============================================== |
There was a problem hiding this comment.
| 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.
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.
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.
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.
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.
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.
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.
We can also link to PEP 4
| :maxdepth: 5 | ||
|
|
||
| communication-channels | ||
| cpython-deprecation-workflow |
There was a problem hiding this comment.
This should definitely be below development cycle
3 participants
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/