Repository navigation
Docs: move deprecations into include files #122085
Description
Activity
- added 6 commits that reference this issue
on Jul 24, 2024 - added 6 commits that reference this issue
on Jul 27, 2024 Anything left outstanding?
A
@ezio-melotti and @encukou discussed some rearrangements in #121241 (comment), now is a good time for that. What did you have in mind?
What did you have in mind?
I'm looking at the ToC of What's new in 3.13, which looks like:
... Optimizations Removed Modules And APIs ... New Deprecations Pending Removal in Python 3.14 Pending Removal in Python 3.15 Pending Removal in Python 3.16 Pending Removal in Future Versions CPython Bytecode Changes C API Changes New Features Build Changes Porting to Python 3.13 Changes in the Python API Changes in the C API Removed C APIs Deprecated C APIs Pending Removal in Python 3.14 Pending Removal in Python 3.15 Pending Removal in Future Versions Regression Test Changes ...There are a few issues here:
- The "Pending Removal"s don't seem to belong under "New Deprecations", assuming they also include existing deprecations carried over from previous versions.
- It also seems that some (all?) new deprecations are also duplicated under the "Pending Removal"s.
- All these sections except "Pending Removal in Future Versions" have no introductory paragraph to explain briefly what are they listing (possibly including the fact that some entries are duplicated and that old deprecations are included too).
- Under "Porting to Python 3.13" there's another set of "Pending Removal"s, with no clear indication of the difference with the previous set. Since the title is the same, it creates a conflict in the link fragment (and the fragment is replaced by an
#idxx) - This part also doesn't mirror the previous one, with "Deprecated C APIs" seemingly being the C equivalent of the previous "New Deprecations", even though it's now on the same level.
- This new set of "Pending Removal"s seems to be about C APIs, but this is not clear from the title, and it's also not explicitly mentioned in the sections themselves.
- The "Porting to Python 3.13" section should arguably also contains the first set of "Pending Removal"s, or maybe both sets should be moved before and referenced where needed.
- "Pending Removal in Python 3.16" is missing from the second set (maybe intentionally if there are no new deprecations? should it still be added with a short note stating that there are currently no deprecations about features removed in 3.16?)
Taking a step back, we might want to separate both Python changes from C changes (this applies to rest too) or new vs existing deprecations (this only applies to deprecation), i.e.:
Python changes New APIs Deprecations New Deprecations Pending removal in 3.x Pending removal in future versions C changes New APIs Deprecations New Deprecations Pending removal in 3.x Pending removal in future versionsor
... New APIs Python APIs C APIs Deprecations New Deprecations Python Deprecations C Deprecations Pending removal in 3.x Python C ... Pending removal in future versions Python CIOW, either the structure of the document is confusing (and should be fixed), or I am misunderstanding it (which probably means that it's confusing (and should be fixed)).
Reacted by Petr ViktorinI've done what I initially intended with this issue am not planning on working further on this, @ezio-melotti please open a new issue for #122085 (comment) or parts of it, if you'd like to take those forward. Thanks!
Documentation
Re: https://discuss.python.org/t/streamline-whats-new-by-moving-deprecations-and-removals-out-of-news/53997/8
To avoid needing to duplicate and sync the deprecation sections across What's New files, and ease backports, move them into include files.
whatsnew/3.12.rstdeprecationswhatsnew/3.13.rstdeprecationswhatsnew/3.14.rstdeprecationsLinked PRs
whatsnew/3.13.rstdeprecations #121241whatsnew/3.13.rstdeprecations (GH-121241) #122038whatsnew/3.12.rstdeprecations #122093whatsnew/3.12.rstdeprecations (GH-122093) #122223whatsnew/3.12.rstdeprecations, including 3.16 (GH-122093) #122225whatsnew/3.12.rstdeprecations (GH-122093) #122224whatsnew/3.14.rstdeprecations #122242whatsnew/3.14.rstdeprecations (GH-122242) #122350whatsnew/3.14.rstdeprecations (GH-122242) #122351