Streamline "What's New" by moving deprecations and removals out of News?

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.rst3.13.rst3.12.rst etc.) and branches (main3.133.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:

12 Likes