-
-
Notifications
You must be signed in to change notification settings - Fork 30.5k
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
Enforce the use of deprecated-removed
in docs
#92564
Comments
Note, some C APIs are deprecated but still kept, in order to maintain ABI compatibility, so I think there's still need for the |
|
For those cases, we could either keep using |
That's a very good point, Ezio; providing more context is always a good thing. |
This conflicts with our practice where we sometimes wait longer than required to actually remove a feature. Also, you've marked this as applying to previous versions of the docs. We don't normally backport doc changes beyond the current version unless they are actual bug fixes (incorrect docs). |
If this happens then no harm is done -- we can just updated the target and people that already updated their code won't have to worry about it anymore, people that didn't will have some extra time.
There are some conflicting opinions (we were just discussing this on Discord). Backporting is useful for people reading docs for older versions and prevents merge conflicts while backporting actual bugs. Are there any disadvantages in backporting them (other than the extra time required to check for @miss-islington)? |
I think you need to adjust your "we"; there are different practices and opinions amongst the core devs. |
As a "regular" Python user (er, well, docs team member, PEP editor and triager, but not a core dev), I'd strongly err on the side of being explicit over implicit and specifying something with regard to the removal version, even if that's If a specific 3.x version is known (or can be decided on), it is very helpful to state that up front, even if is later pushed back, in order to be able to plan around it as a library maintainer who wants to support a reasonably wide range of Python versions, and a FOSS application developer with limited bandwidth who wants to prioritize addressing things that will be actively removed soon; not only is this helpful for users like myself who actively watch, test for and fix deprecations, but also in convincing others convincing others of the necessity of doing so. And if one is not known (yet), in a future major release or the deprecation is forseeably indefinite, this is likewise very helpful, as it both helps explicitly document (for both users and contributors) that an exact removal version is not yet planned, without having to dig through old threads, ask people or get blindsided by an unexpected removal, and these individual distinctions are still important and can result in different appropriate choices as both a Python user and a contributors.
@hugovk @brettcannon I really don't understand the reason for providing the target removal version up front in the DeprecationWarning (which unfortunately many devs will never see, at least not in a timely manner), but hiding it in the actual documentation, unless users click the link and dig through the PEP? As discussed above, many deprecated items have been deprecated for years or even a decade or more, and some even potentially indefinitely, the lack of a removal version does not convey any of the actual urgency of the imminent complete removal. Furthermore, I'd think it is much better to err on the side of caution, make the current planned removal date clear so users can respond to it with appropriate urgency, rather than encouraging complacency until it is too late to either address or revert it. If the concern is the possibility it may be pushed back, the docs can be updated instantly, whereas it is much harder and slower to update released Python versions, if that is possible at all, and @brettcannon you yourself mentioned on the PEP 594 Discourse thread that the PEP is now considered a historical document. And as we saw with PEP 563 and others, clearly establishing an initial set date is a great catalyst for users and ecosystems testing the change and sharing any unanticipated impacts that might justify such a delay, before it is too late. |
In this specific case, it's because we backported the deprecation warning which we rarely do. But if the target removal version slips and a Python version is in maintenance mode, we don't want to go back and edit the docs just to fix that sort of discrepancy. Backporting the deprecation notice while leaving out the removal version also came from the SC as part of the PEP's acceptance. |
I can see the argument for not backporting deprecation messages to begin with, so that past Python versions don't show a future Python version as the deprecation version. But particularly given the value of an explicit removal version, I don't understand how backporting categorically changes the calculus on removal versions from any other deprecation, since even with no backporting and a deprecation for the minimum two releases, the version the deprecation message was added in will still no longer be in bugfix mode a minimum of six months prior to the release of the version with the functionality removed, and in many cases much longer. I can bring the broader docs backport policy issue up with the Docs Team and |
I'm fine with what you're proposing for 3.11 onward, but not backporting to earlier versions. |
Sorry for any confusion—that is what I'm proposing for now ("the deprecation version" == "3.11") 😉 |
…es (GH-92793) As discussed in #92611 and #92564 and as a followup to PR #92612 , this 3.11+ only PR uses the proper `deprecated-removed` role for the modules deprecated by PEP 593 (PEP-594) to clearly indicate to users that a removal version is planned and what it is, so they can prepare accordingly or voice any unanticipated impacts. Related to #92792 ; if we decide to backport that PR, the upgrade to using `deprecated-removed` on those functions can be moved to this one.
… modules (pythonGH-92793) As discussed in pythonGH-92611 and pythonGH-92564 and as a followup to PR pythonGH-92612 , this 3.11+ only PR uses the proper `deprecated-removed` role for the modules deprecated by PEP 593 (PEP-594) to clearly indicate to users that a removal version is planned and what it is, so they can prepare accordingly or voice any unanticipated impacts. Related to pythonGH-92792 ; if we decide to backport that PR, the upgrade to using `deprecated-removed` on those functions can be moved to this one. (cherry picked from commit 31fa41e) Co-authored-by: CAM Gerlach <[email protected]>
…es (GH-92793) (GH-93026) As discussed in GH-92611 and GH-92564 and as a followup to PR GH-92612 , this 3.11+ only PR uses the proper `deprecated-removed` role for the modules deprecated by PEP 593 (PEP-594) to clearly indicate to users that a removal version is planned and what it is, so they can prepare accordingly or voice any unanticipated impacts. Related to GH-92792 ; if we decide to backport that PR, the upgrade to using `deprecated-removed` on those functions can be moved to this one. (cherry picked from commit 31fa41e) Co-authored-by: CAM Gerlach <[email protected]>
… modules (pythonGH-92793) As discussed in python#92611 and python#92564 and as a followup to PR python#92612 , this 3.11+ only PR uses the proper `deprecated-removed` role for the modules deprecated by PEP 593 (PEP-594) to clearly indicate to users that a removal version is planned and what it is, so they can prepare accordingly or voice any unanticipated impacts. Related to python#92792 ; if we decide to backport that PR, the upgrade to using `deprecated-removed` on those functions can be moved to this one.
In the docs we have two directives that can be used to document deprecations:
deprecated
anddeprecated-removed
.I think we should always prefer the latter:
Even if the removal version gets postponed, it's better to postpone than to say that something is deprecated and then just remove it at an unspecified time in the future.
Currently
deprecated
is more commonly used:deprecated-removed
deprecated
directive and replace it withdeprecated-removed
The text was updated successfully, but these errors were encountered: