During the PyconUS2024 Core sprints, I noticed some chatter along the lines of:
Let’s streamline what’s New by referencing Deprecations and Removals
Something like:
Doc/whatsnew/deprecations/removal.rst
Doc/whatsnew/deprecations/removalpending.rst
Doc/whatsnew/deprecations/deprecations.rst
The discussion started during a triage of random docs PRs:
I’m not sure where to take this so I will write some notes here and drop it on the agenda.
Sorry, it wasn’t quite clear to me: would this restructuring also be reflected in the corresponding webpages (i.e. https://docs.python.org/3/whatsnew/x.y.html)? Or is it only about internal structure of the .rst source files?
I suspect everything there has been requested. I like having the complete listing in one place.
For the past couple of releases, we’ve been collating all the pending deprecations in the What’s New page, not just those new deprecations in this release. For example: What’s New In Python 3.12 — Python 3.12.3 documentation
This makes the What’s New page longer, and I also don’t think it’s the right place to put them all.
Instead, I suggest we have a single dedicated page (actual structure TBD) to list all the current pending deprecations. Then, in “What’s New in Python 3.x”, we should only list the deprecations newly added in that release.
For example, if we deprecate something in 3.11, pending removal in 3.14, we list it in What’s New in Python 3.11 and the deprecations page, and not again in What’s New in Python 3.12, What’s New in Python 3.13 and What’s New in Python 3.14.
The new deprecations page is a living document; we list all pending deprecations, and when the deprecation is removed, we delete it or move it to a “removed” section. Some deprecations will be kept for a long time/“forever”, we list them here too.
This means we don’t need to worry about synchronising across both pages (3.14.rst ↔ 3.13.rst ↔ 3.12.rst etc.) and branches (main ↔ 3.13 ↔ 3.12).
And we sometimes do forget to update them, for example, python/cpython#118947. Additionally, at some point a branch goes to security-fix only, and we can no longer update the old What’s New.
Compare the pytest page:
As a user of pytest, this is a useful one-stop page to look where I need to update my code.
I copied it for Pillow:
As a maintainer of Pillow, this is a useful one-stop page to look for old deprecations to remove in the next release.
Previous discussion:
This seems like a great idea generally; but if I’m not on the newest version, I think I’d like to be able to filter that easily so it only shows what’s deprecated in the version I’m using. Or maybe sort it by deprecation version, etc.
Wouldn’t we mention in What’s New in Python 3.14 that the announced removal happened? So we deprecate in 3.11 and mention it in the 3.11 What’s New, then remove it in 3.14 and mention that in the 3.14 What’s New. But no mention in 3.12 and 3.13.
Yes, exactly, thanks for the correction!
We discussed this at this week’s docs community meeting (notes here; at some point will be moved here), and came up with the idea of moving each version’s deprecations into its own RST file.
Then we can .. include:: them in each relevant What’s New page, plus a dedicated deprecations page. That way we avoid duplicating the information and don’t need to worry about syncing across pages.
Please see PR python/cpython#121241 to make a start on this.