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

Core Development
1

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?

13 Likes
2

Better advertizing deprecations and removals is a good idea.

4 Likes
3

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:

https://docs.pytest.org/en/7.1.x/deprecations.html#deprecations

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?

2 Likes
4

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: https://github.com/python/cpython/issues/92564)

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

3 Likes
5

+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
6

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

3 Likes
7

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.

5 Likes