Proposal: "Pending Removal" category in What's New

We currently have Deprecated and Removed sections in What’s New. I think it would be wise to emphasise future removals by also mentioning them in “in-between” versions, by introducing a Pending Removal section.

Example, deprecating method spam.eggs() in 3.11, scheduled for removal in 3.13:

  • 3.11 What’s New, Deprecated: undocumented method spam.eggs() is deprecated, scheduled for removal in Python 3.13
  • 3.12 What’s New, Pending Removal: deprecated method spam.egg() is pending removal, scheduled for removal in Python 3.13
  • 3.13 What’s New, Removed: deprecated method spam.egg() is removed

What do you all think?


Better advertizing deprecations and removals is a good idea.


Good idea! Would be great to get this included for Friday’s first 3.11 beta.

Similarly, pytest has a dedicated page for deprecations and removals:

Which I copied for Pillow:

As a (pytest) user and (Pillow) maintainer I find these lists useful: to respectively check where I need to change my code, what needs to be removed in the next release.

Would a dedicated page be useful for CPython too?


I think it would, especially if we can generate it (mostly) automatically. This should be doable, since all deprecated features should be marked with either the deprecated or the deprecated-removed Sphinx directives. (Side note: we should use deprecated-removed more often, since currently we have 30 compared to 225 deprecated – Edit: Enforce the use of `deprecated-removed` in docs · Issue #92564 · python/cpython · GitHub)

The whatsnew could either just link to this new page, or its content could be copied into the whatsnew at release time.


+1 for that kind of automation, @ezio-melotti. For 3.11, I think we must do it manually, but we should try to get such a framework up for 3.12.

1 Like

May I put a topic about PEP 686 in the section?
It is not future removal, but future backward incompatible change.


Seems like everyone approves of this. Let’s try and get this into 3.11 beta1 What’s New.

I created gh-92308 (issue) and gh-92309 (PR). Please take a look a tell me what’s missing! Feel free to add directly to the PR, if you are able.