# Streamline "What's New" by moving deprecations and removals out of News? **URL:** \ **Category:** Documentation\ **Tags:** documentation\ **Created:** [May 22, 2024, 7:25pm UTC](https://discuss.python.org/t/streamline-whats-new-by-moving-deprecations-and-removals-out-of-news/53997 "2024-05-22T19:25:49Z")\ **Posts on this page:** 9\ **Page:** 1
**Author:** ![blaisep](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/blaisep/32/1978_2.png) [@blaisep](https://discuss.python.org/u/blaisep)\ **Post date:** [May 22, 2024, 7:25pm UTC](https://discuss.python.org/t/streamline-whats-new-by-moving-deprecations-and-removals-out-of-news/53997/1 "2024-05-22T19:25:49Z")
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: ```shell 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: > > > (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? I’m not sure where to take this so I will write some notes here and drop it on the agenda. ---
**Author:** ![kknechtel](https://avatars.discourse-cdn.com/v4/letter/k/e47c2d/32.png) [@kknechtel](https://discuss.python.org/u/kknechtel)\ **Post date:** [May 22, 2024, 9:12pm UTC](https://discuss.python.org/t/streamline-whats-new-by-moving-deprecations-and-removals-out-of-news/53997/2 "2024-05-22T21:12:51Z")
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? ---
**Author:** ![tjreedy](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/tjreedy/32/137_2.png) [@tjreedy](https://discuss.python.org/u/tjreedy)\ **Post date:** [May 23, 2024, 4:46am UTC](https://discuss.python.org/t/streamline-whats-new-by-moving-deprecations-and-removals-out-of-news/53997/3 "2024-05-23T04:46:24Z")
I suspect everything there has been requested. I like having the complete listing in one place. ---
**Author:** ![hugovk](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/hugovk/32/14505_2.png) [@hugovk](https://discuss.python.org/u/hugovk)\ **Post date:** [May 23, 2024, 8:54am UTC](https://discuss.python.org/t/streamline-whats-new-by-moving-deprecations-and-removals-out-of-news/53997/4 "2024-05-23T08:54:56Z")
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](https://docs.python.org/3/whatsnew/3.12.html#deprecated) 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](https://github.com/python/cpython/pull/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: - [Deprecations and Removals - pytest documentation](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: - [Deprecations and removals - Pillow (PIL Fork) 10.3.0 documentation](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. * * * Previous discussion: - [Proposal: "Pending Removal" category in What's New](https://discuss.python.org/t/proposal-pending-removal-category-in-whats-new/15470) - [Experience with Python 3.11 in Fedora - #16 by hugovk](https://discuss.python.org/t/experience-with-python-3-11-in-fedora/12911/16) ---
**Author:** ![kknechtel](https://avatars.discourse-cdn.com/v4/letter/k/e47c2d/32.png) [@kknechtel](https://discuss.python.org/u/kknechtel)\ **Post date:** [May 23, 2024, 7:20pm UTC](https://discuss.python.org/t/streamline-whats-new-by-moving-deprecations-and-removals-out-of-news/53997/5 "2024-05-23T19:20:45Z")
> [@hugovk](#): > > As a user of pytest, this is a useful one-stop page to look where I need to update my code. 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. ---
**Author:** ![nedbat](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/nedbat/32/8744_2.png) [@nedbat](https://discuss.python.org/u/nedbat)\ **Post date:** [May 23, 2024, 7:54pm UTC](https://discuss.python.org/t/streamline-whats-new-by-moving-deprecations-and-removals-out-of-news/53997/6 "2024-05-23T19:54:42Z")
> [@hugovk](#): > > 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. 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. ---
**Author:** ![hugovk](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/hugovk/32/14505_2.png) [@hugovk](https://discuss.python.org/u/hugovk)\ **Post date:** [May 23, 2024, 8:10pm UTC](https://discuss.python.org/t/streamline-whats-new-by-moving-deprecations-and-removals-out-of-news/53997/7 "2024-05-23T20:10:33Z")
Yes, exactly, thanks for the correction! ---
**Author:** ![hugovk](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/hugovk/32/14505_2.png) [@hugovk](https://discuss.python.org/u/hugovk)\ **Post date:** [June 7, 2024, 5:52pm UTC](https://discuss.python.org/t/streamline-whats-new-by-moving-deprecations-and-removals-out-of-news/53997/8 "2024-06-07T17:52:11Z")
We discussed this at this week’s docs community meeting (notes [here](https://hackmd.io/_vyolH-NR3GQHoOUjqdzuQ); at some point will be moved [here](https://docs-community.readthedocs.io/en/latest/monthly-meeting/index.html)), 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. ---
**Author:** ![hugovk](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/hugovk/32/14505_2.png) [@hugovk](https://discuss.python.org/u/hugovk)\ **Post date:** [July 1, 2024, 8:04pm UTC](https://discuss.python.org/t/streamline-whats-new-by-moving-deprecations-and-removals-out-of-news/53997/9 "2024-07-01T20:04:28Z")
Please see PR [python/cpython#121241](https://github.com/python/cpython/pull/121241) to make a start on this.