GeezerVison

If you move these sub-sections of the C API section, you should also move the other ones of the "main" Python section: moving "Pending Removal in Python 3.14" after Removal. What do you think?

Personally, I probably wouldn't as I think semantically it makes more sense to note the pending removals for Python APIs within the Deprecated section -- they are a concise list of how quickly readers will need to adapt to the new APIs.

A

they are a concise list

My concern is more that these lists are getting bigger at every Python version. Sometimes, I'm considering to create a sub-page of What's New in Python 3.13, since the document is so big, that people may give up to just start reading it. Deprecation/Removal only interest a minority of people.

The whole What's New in Python 3.13 takes 18 pages if I print it as PDF with my default browser configuration.

I don't have a strong opinon between:

• Deprecations

  • Pending Removals ...

• Removal

VERSUS:

• Deprecations
• Removal
• Pending Removals ...

I would just prefer to have consistency between the (main) Python section and the C API Changes section.

If you prefer to have "Pending Removals ..." under the Deprecations section, please just make it consistent in the doc.

My concern is more that these lists are getting bigger at every Python version. Sometimes, I'm considering to create a sub-page of What's New in Python 3.13, since the document is so big, that people may give up to just start reading it. Deprecation/Removal only interest a minority of people.

I agree with this.

I want us to have a static page of pending deprecations, so we don't need to worry 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 #118947. Additionally, at some point a branch goes to security-fix only, and we can no longer update the What's New.

Then, in "What's New in Python 3.x", we should only list the deprecations newly added in that release.

Compare the pytest page:

• https://docs.pytest.org/en/latest/deprecations.html

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:

• https://pillow.readthedocs.io/en/stable/deprecations.html

As a maintainer of Pillow, this is a useful one-stop page to look for old deprecations to remove in the next release.

(OK, I can see that there is more to this than I originally thought)

It seems like the current consensus is to have something like

Doc/whatsnew/deprecations/removal.rst
Doc/whatsnew/deprecations/removalpending.rst
Doc/whatsnew/deprecations/deprecations.rst

and possibly some Doc/whatsnew/deprecations/index.rst with a bit of .. toctree:: sugar sprinkles?
Shall I bring this up in the docs discord?

Follow on from this. We discussed this on Discourse:

• https://discuss.python.org/t/streamline-whats-new-by-moving-deprecations-and-removals-out-of-news/53997

And in the docs-community meeting last month, where we thought about using includes:

• https://docs-community.readthedocs.io/en/latest/monthly-meeting/2024-06.html#python-project-documentation

• https://discuss.python.org/t/streamline-whats-new-by-moving-deprecations-and-removals-out-of-news/53997/8

Please see PR #121241 to make a start on this.

With apologies for the force-push, I have hijacked my own PR to use the include-file approach for the C API, whilst still doing the synchronisation.

I've split the work into individual commits, which should be somewhat easy to follow.

A

Is it so that we weren't previously duplicating all the C API deprecations across What's New files?

This will mean the What's New pages will become even longer. But I suppose if we do it for the Python deprecations, that's an argument for also doing it for the C API ones too.

Is it so that we weren't previously duplicating all the C API deprecations across What's New files?

Almost all of the deprecations were in both 3.12 and 3.13, it was only 3.14 that was sparse, so I think it is worth both ensuring there's consistency and that we advertise the deprecations in all What's New pages.

A

Would you like to add these includes to the new deprecations/index.rst from #122352?

I also realised we don't want .. include:: pending-removal-in-3.14.rst here in main (aka 3.14), we only want to list later versions:

The backports are correct:

• https://github.com/python/cpython/blob/3.13/Doc/deprecations/index.rst
• https://github.com/python/cpython/blob/3.12/Doc/deprecations/index.rst

Please could you also remove that line at the same time?

Would you like to add these includes to the new deprecations/index.rst

Done

Please could you also remove that line at the same time?

Done

A

Thanks @AA-Turner for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

Sorry, @AA-Turner, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 76bdfa4cd02532519fb43ae91244e2b4b3650d78 3.13

Sorry, @AA-Turner, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 76bdfa4cd02532519fb43ae91244e2b4b3650d78 3.12

GH-122422 is a backport of this pull request to the 3.13 branch.

GH-122423 is a backport of this pull request to the 3.12 branch.