docs-community
docs-community copied to clipboard
python
Cut the whale of the changelog into manageable pieces?
The changelog page is very long:
- https://docs.python.org/dev/whatsnew/changelog.html
It's currently 219,974 words, that's longer than Moby Dick (212,794 words)... 🐳
It contains all the NEWS entries back to Python 3.5.0 alpha 1 (February 8, 2015).
It loads okay on deskstop, but my phone struggles to render it, and the browser hangs when trying to search for text.
I tried to check the accessibility report using Google's PageSpeed Insights:
- https://pagespeed.web.dev/analysis/https-docs-python-org-dev-whatsnew-changelog-html/9zu7fhwlzu?form_factor=mobile
It shows good initial numbers:
But the rest of the report is missing: "Oops! Something went wrong. generic::deadline_exceeded: Render timeout received in extension."
Shall we break the changelog page into smaller, more manageable chunks?
Right now, the changelog.rst page includes the NEWS file:
.. _changelog:
+++++++++
Changelog
+++++++++
.. miscnews:: ../build/NEWS
https://github.com/python/cpython/blob/3d5df54cdc1e946bd953bc9906da5abf78a48357/Doc/whatsnew/changelog.rst
The 43,720-line NEWS is compiled by blurb from the individual release files in https://github.com/python/cpython/tree/main/Misc/NEWS.d:
Building NEWS from Misc/NEWS.d with blurb
https://github.com/python/cpython/blob/3d5df54cdc1e946bd953bc9906da5abf78a48357/Doc/Makefile#L50-L66
I think splitting to major versions at least makes sense (so potentially /changelog/3.13.html, akin to /whatsnew/blah.html?)
There's an argument to break further, to e.g. a page per micro release, but I think that would inder Ctrl-F searching within each version.
A
This was discussed at the Feb 2024 docs meeting: https://github.com/python/docs-community/blob/main/docs/monthly-meeting/2024-02.md
The general consensus was that splitting the changelog makes good sense. Let's add to March 2024 agenda for next steps.
There's an argument to break further, to e.g. a page per micro release, but I think that would inder Ctrl-F searching within each version.
There is also a form to filter changes, so that people can easily enter the name of a module/function and see all the changes that affected it. This was broken and got fixed recently in:
- python/cpython#115324
For this specific use case, having everything on one page is convenient, but if we kept at least the last 3 versions on a single page, it would probably be good enough. By doing this we could reduce the overall size to ~1/3.
When I use the changelog, I use Ctrl+F to look for the history of a function or feature. On the detail/noise spectrum, the changelog is somewhere between whatsnew & versionchanged notes on one side, and Git history on the other. And the changelog tends to work better for things that were renamed or moved around.
This use case might be an outlier, so it might be OK to break it. But: do we know of any other use for the changelog?
The newly restored changelog filter looks good; maybe it could be taught to display entries from old versions in the main document?
if we kept at least the last 3 versions on a single page, it would probably be good enough.
It might even be reasonable to trim that list to the last 5 minor versions, which covers everything that was in the "supported" window for CPython (with the newer annual releases + 5 year support cycle).
One thing we could do is add a warning to the link to the changelog, warning people to not open it on a phone.
We can’t do that in all websites and search engines that link to the changelog, though.
