-
-
Notifications
You must be signed in to change notification settings - Fork 31k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Policy for removal of old .. versionadded
|.. versionchanged
?
#108514
Comments
It is an useful information to me. Why do you want to remove it? |
for say 3.6-3.12 I find it useful, but I find it adds cruft in some area. For example:
Couldn't the But another
At that point do the "new in version 3.1" really bring useful information as a first item to inform the use in the skipping test and expected failures ? |
I don't have a strong opinon about it, I will not block if you propose a change :-) I'm not concerned by Changelog which goes up to Python 3.5.0! Maybe it's time to cut it :-) |
It was discussed on the core dev Discord fairly recently. To summarise:
|
The current policy is that the Python x (3) manual should have a complete history of feature changes so that one can write and maintain code compatible with any minor x.y (3.y) version. The premise of this proposal seems to be that is that no one writes or maintains code for 3.5 or earlier. I doubt that this is true for the wider Python community. In any case, I think that this documentation policy change should be discussed on discourse, just as major code changes should be discussed on the Ideas channel. This issue could be closed and reopened later. Note 1: AFAIK, no notices in the Python 2 manual were ever removed. On the other hand, there were just 8 Python 2 versions over a decade, at which point Python 2 and its manual were essentially feature frozen. Note 2: When 3.0 came out, it was anticipated that we would be distributing Python 4 now, with a new manual tracking changes from 4.0. (Releasing 3.10 required removing the assumption in several places that 1 digit was enough for the minor version number.) Since that has not happened yet, I think revising the policy can be considered. Note 3: PyPI searches in a browser do not seem directly useful for ongoing guidance as to what changes to make. Searches https://pypi.org/search/?q=&o=&c=Programming+Language+%3A%3A+Python+%3A%3A+3.0 (and .1, .2, .3) give 647, 1435, 5469, and 10000+ hits (and 10000+ up to 3.11). Dead packages tend to hang around, while we would be more interested in active projects that drop older versions. |
I personally don't really mind seeing them at least back to Python 3.0 as they're not that numerous (relative to the size of the docs) or intrusive, and we of course certainly shouldn't spend valuable time mechanically removing semantically meaningful information from the source. Though, I don't feel too strongly about hiding annotations for Python <≈3.4-3.5 or so in the rendered output, if its agreed upon by others. Whatever minimum version we agree on, 3.0, 3.6 or something in between, it would be trivial to implement this via via a Sphinx post-transform that checks for I've opened a PR, #108522 , with a working implementation, if/when we agree on a minimum value, or we could specify 3.0 for starters as the status quo, and change it later if agreed. One other point to note is that seeing an annotation for a version well older than anything than I support gives me affirmative confirmation that I can safety use an API, whereas not showing it adds a kernel of doubt that perhaps the annotation was simply omitted (of course, with reasonably complete annotations in the source and a couple additional bits of inline structured data, we avoid the latter concern by programmatically validate that all public APIs have the version they were added documented in their metadata, which is something I'm currently working on). Summary of previous discussion/proposalsFor posterity, there has been previous recent discussions about this among the core devs; the main approach that was considered and generally seemed to be agreed upon at the time was to make old To summarize, on the backend side, its pretty trivial do so; just add a The frontend side is simple in theory—add e.g. an HTMLTranslator to wrap marked I am already actively working on both of those blockers because grouping and sorting the list has been requested and is potentially beneficial anyway, and it allows us to do a number of other things that have been requested (statically/programmatically exposing deprecation, etc. information, automatically collating changes/deprecations/removals in the What's New, a dedicated page, etc.). However, while a hide/show option the cases where it is potentially the most bothersome (long lists of changes for the same object over different versions), it doesn't really help for the ≈majority of such annotations that are standalone. Here's my detailed comments and design for how that can be implemented, from that discussion: Detailed proposal for user-controlled hide/show
|
Thanks, I'll use my best judgement if I see anything that could be written better or maybe remove. I just want to make sure there is no "keep everything" policy. |
@Carreau To summarize my interpretation of the discussions here and elsewhere, the general consensus seems to be that older However, you bring up the good point that there are cases where significant information/explanation is contained within the versionchanged rather than in the prose proper and likely should be moved to the latter if it exists already or is still useful, or otherwise considered for removal from the message. Indeed, as @AA-Turner lists in detail on the PR, there seems to be a fair number of cases where this is so. Therefore, for those it seems it would be of value to move such detailed information to the prose instead, leaving just a brief summary in the |
I wrote a little Sphinx plugin years ago for Pallets/Flask for this exact case where we had years of changes that were interesting but noisy. The plugin ensures the change entries are sorted most recent first, then collapses everything but the previous version. https://pypi.org/project/sphinxcontrib-log-cabinet/ If you think that's useful, I wouldn't mind maintaining it if anything is needed. |
A large number of
.. versionadded
, and.. versionchanged
directive are from long-unmaintained version of Python, from a rough search through the codebase/docs (excluding whatsnew), of everything 3.5 and before:I think that at some point it might be useful to remove those, and write the documentation as if what was changed/added has always be present.
Is there any policy as to when those can/should be removed/rephrased ?
Linked PRs
The text was updated successfully, but these errors were encountered: