Repository navigation
Document the workflow for deprecating something in CPython. #1419
Description
Describe the enhancement or feature you'd like
Document the workflow on how to deprecate something in CPython.
Deprecating something in Python involves raising deprecation warning and then actually removing the code some time later (at least 2 release cycles). We don't have this process documented clearly.
Describe alternatives you've considered
Currently this is undocumented process, and each of us has to just figure it out somehow.
Additional context
Discussed on Discord core-workflow-and-bots channel, and now opening a ticket based on the discussions.
Basic process:
- An issue was opened calling for deprecation of something
- We deprecate the code by adding warnings.deprecated (or warnings._deprecated)
- Document the deprecation. Needs a Porting doc (how?)
- The issue can be closed after the code for adding deprecation has been merged. It doesn't need to stay open for 2+ more years.
- Add the deprecation to the
pending-removal-in....rstfile - At the scheduled removal year, open a new issue for the removal
- Finally remove the code
Other info:
- Some deprecations don't have set removal date.
- There are also deprecated-removed Sphinx role to help advertise the removal dates.
- How to decide whether Removal/Deprecation is the right solution?
- search the usage, search on GitHub, grep, check PyPI projects to get an idea of the widespread usage
- when searching, look not just if people are using it, but how they're using it. Document the use case for the porting notes
- Is there a template for deprecation warning message?
- Should have documentation about how to port/replace it (porting notes)
- Users are encouraged to give feedback about deprecation by filing an issue
Note there is an open proposal for extending the removal of deprecated code to 5 years instead of 2.
Activity
encukou commentedon Sep 27, 2024
This process is documented in PEP-387's Making Incompatible Changes section.
It mentions the 2-release minimum, but also:
Also there's a "See if there’s any feedback" step, discussion, typeshed, and a mention of
Py_DEPRECATEDfor C API deprecations.hugovk commentedon Sep 27, 2024
PEP 387 is the policy, and indeed includes the minimum and recommendations about a longer deprecation period.
However, I think it would be useful to have a practical guide in the devguide about the concrete steps (usually) needed, which don't belong in the PEP.
The devguide instructions should of course refer to the PEP for the policy details.
Mariatta commentedon Sep 27, 2024
Hmm, I was expecting to find this info on the devguide, under Development Workflow.
I think some docs in the peps repo really should be more in the devguide instead of the PEP, or perhaps the PEP can be the proposal, the background story.
The PEP also doesn't say stuff like: go add this to the pending-removal-in .. file.
So yeah I agree with Hugo, to have the detailed instructions in the devguide, and then add the
.. seealso::to the PEP.
encukou commentedon Sep 27, 2024
IMO, a Process PEP should list the formal requirements, and the devguide should say how to meet them in practice. So, yes, please add this to Devguide! After that we can trim the PEP and have it link to devguide.
Mariatta commentedon Sep 28, 2024
What is the workflow for "PendingDeprecationWarning"?
encukou commentedon Oct 1, 2024
AFAIK, we don't use PendingDeprecationWarning in CPython any more.
Lincoln-developer commentedon Nov 5, 2024
Hey @Mariatta I would love to work on this issue if no one is working on it. Thanks.
Mariatta commentedon Nov 5, 2024
Hi @Lincoln-developer, yes please go ahead and create the PR.