Description

e-gebes

opened on Jun 20, 2024

Issue body actions

Documentation

For issue #90562, which is not yet fixed, the documentation has been updated to mention the issue for 3.12 and 3.13, but a request to backport it further to 3.10 was replied with a link https://devguide.python.org/versions/ that only security fixes are allowed for 3.10.

Since 3.10 and all security branch releases are obviously expected to be used, it makes sense to be able to expect the documentation can be relied on as well. End-of-life versions like 3.7 have a red banner at the top of each documentation page:

This document is for an old version of Python that is no longer supported. You should upgrade, and read the Python documentation for the current stable release.

It's clear to the reader that also the doc pages are not maintained and might be outdated.

I suggest to consider either

• Allow documentation fixes and additions of caveats for security branch releases if this does not involve changing actual source code files (docstrings). In the case mentioned above, the file https://github.com/python/cpython/blob/3.10/Doc/library/dataclasses.rst would be affected which is not such a source code file.

or

• Add a yellow banner notice on top of each documentation page for security branch releases, making it clear that the documentation is not maintained anymore. (In style similar to the red banner for end-of-life releases.)

Activity

1. e-gebes

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   on Jun 20, 2024
2. terryjreedy commented on Jun 20, 2024

   

   terryjreedy

   on Jun 20, 2024

   Member

   More actions

   No to the first option. We simply do not have the personpower to keep each version of the docs in the best shape possible throughout the whole 7-year release cycle. I quite suspect you underestimate the time involved. Or, to put it another way, we consider improving current and recent versions (feature and bugfix versions) to be relatively more important.

   The EOL banner is intended to be a bit obnoxious and attention-grabbing. lTo me, it is more important for security release that the code is almost frozen. Is 'security fixes only' not obvious enough? In any case, a banner, if any, should just say that this applies to both code and docs.

   The sidbar for https://docs.python.org/3/ labels each release. The EOL banner is for newcomers who might not understand 'EOL'. Hence the additional suggestion to use a 'stable' version.

   Reacted by Nice Zombies
3. ericvsmith

   added

   pendingThe issue will be closed if no feedback is providedThe issue will be closed if no feedback is provided

   and removed

   pendingThe issue will be closed if no feedback is providedThe issue will be closed if no feedback is provided

   on Sep 23, 2024
4. ericvsmith commented on Sep 23, 2024

   

   ericvsmith

   on Sep 23, 2024

   Member

   More actions

   I suggest anyone who wants to pursue this create a discussion on https://discuss.python.org/c/documentation/26

   Reacted by Terry Jan Reedy
5. ericvsmith

   closed this as not plannedon Sep 23, 2024

Issue actions