René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Document the workflow for deprecating something in CPython.","articleBody":"**Describe the enhancement or feature you'd like**\r\nDocument the workflow on how to deprecate something in CPython.\r\nDeprecating 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.\r\n\r\n**Describe alternatives you've considered**\r\nCurrently this is undocumented process, and each of us has to just figure it out somehow.\r\n\r\n**Additional context**\r\nDiscussed on Discord core-workflow-and-bots channel, and now opening a ticket based on the discussions.\r\n\r\n\r\nBasic process:\r\n- An issue was opened calling for deprecation of something\r\n- We deprecate the code by adding warnings.deprecated (or warnings._deprecated)\r\n- Document the deprecation. Needs a Porting doc (how?)\r\n- 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.\r\n- Add the deprecation to the `pending-removal-in....rst` file\r\n- At the scheduled removal year, open a new issue for the removal\r\n- Finally remove the code\r\n\r\nOther info:\r\n\r\n- Some deprecations don't have set removal date.\r\n- There are also deprecated-removed Sphinx role to help advertise the removal dates.\r\n- How to decide whether Removal/Deprecation is the right solution?\r\n  - search the usage, search on GitHub, grep, check PyPI projects to get an idea of the widespread usage\r\n  - when searching, look not just if people are using it, but how they're using it. Document the use case for the porting notes\r\n- Is there a template for deprecation warning message?\r\n- Should have documentation about how to port/replace it (porting notes)\r\n- Users are encouraged to give feedback about deprecation by filing an issue\r\n- \r\nNote there is an open proposal for extending the removal of deprecated code to 5 years instead of 2.","author":{"url":"https://github.com/Mariatta","@type":"Person","name":"Mariatta"},"datePublished":"2024-09-27T22:54:36.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":8},"url":"https://github.com/1419/devguide/issues/1419"}