Details
-
Type:
RFC
-
Status: Implemented
-
Resolution: Done
-
Component/s: DM
-
Labels:None
Description
The current deprecation procedure for Python suggests that the version in which the interface will disappear be stated in the text: "Will be removed after v15." In addition, I propose that the next major version to be released after the deprecation is merged be stated in a version parameter: version="14.0.0". This results in text saying "Deprecated since version 14.0.0." in the deprecation warning as well as appropriate text and highlighting in the Sphinx-generated documentation (DM-20704). Note that the version here should be, according to our deprecation process, either one prior to the "removed after" version in the normal case or the same as the "removed after" version, if a release was anticipated before the next major release, but in any case it is determinable by the code author at the time of writing the deprecation.
Similarly, for pybind11 a version parameter will be added to lsst.utils.deprecated.deprecate_pybind11.
Attachments
Issue Links
Activity
I'd push back on this a little, because a reader not familiar with our deprecation policy won't be able to tell how urgently they need to stop using the deprecated code. In the Python standard library major releases are rare, and code stays deprecated for years; the version keyword seems to be geared towards that kind of environment. I think if we present all our deprecations as "since version X", users will be surprised when the code stops working on the following release.
Krzysztof Findeisen
added a comment - - edited I'd push back on this a little, because a reader not familiar with our deprecation policy won't be able to tell how urgently they need to stop using the deprecated code. In the Python standard library major releases are rare, and code stays deprecated for years; the version keyword seems to be geared towards that kind of environment. I think if we present all our deprecations as "since version X", users will be surprised when the code stops working on the following release. +1 on using the version parameter.
I'm with Krzysztof on the other half of this: I think our deprecation warnings should be explicit on when the removal will occur (and I think I may have written the original recommendation to express that), not on when the deprecation occurred.
The simplest solution seems to be to do both, then. Add the version= parameter with the next major version as well as keep the text in the warning message saying "Will be removed after" with the estimated version for removal (one after the version= version).
In the unusual case where another release occurs before the next major version, both values can be adjusted accordingly.
I have adjusted the RFC description to say "In addition" rather than "Instead".
I will adopt with adding version but not removing the text from the message.
Properly making use of the version parameter seems like a big win to me, especially if it improves the documentation.