Details
-
Type:
RFC
-
Status: Adopted
-
Resolution: Unresolved
-
Component/s: DM
-
Labels:None
Description
Our deprecation procedure involves annotating code which is to be removed in such a way that it produces a warning when is called.
This warning is intended to alert external consumers of the code of upcoming changes, so they can update their own software appropriately.
However, warnings are also generated if DM-provided code calls the deprecated interface. On occasion — when the same routine is called multiple times — this results in a lot of output, which makes it harder for developers to extract useful information from logs, and confuses and alarms users who are deluged with warnings when they run our code.
I propose, therefore, updating the deprecation procedure so that code may only be deprecated when callers of it within the DM codebase have been updated to use its intended replacement.
In some cases, this may be impossible or undesirable. In those cases, I suggest the policy state that explicit approval must be obtained from the DM-CCB before the code can be deprecated.
Attachments
Issue Links
Activity
Whether or not this RFC gets approved, I think that would be a very useful tool.
Krzysztof Findeisen
added a comment - - edited Whether or not this RFC gets approved, I think that would be a very useful tool. I'll just say that I think it is excessive for a marked-as-deprecated user-facing function that calls an internal also-marked-as-deprecated function to require DM-CCB sign-off in order to suppress the internal warning. (The external warning should not be suppressed, of course.) My understanding of DM-22814 is that a user-facing function (or at least one keyword argument thereof) that should have been marked deprecated was inadvertently not so marked, which is a different case.
Adopting this, with DM-23239 as the implementation ticket.
I've suggested some specific wording on that ticket which I'm confident captures the conclusion of this RFC, but which could probably use some further wordsmithing. Please comment on that ticket if you'd like to help refine it.
Pretty sure I figured out the warning suppression thing yesterday: https://github.com/lsst/afw/commit/faee97bfb0ffc3f1b1624ba88f72181b3955ea5f
Obviously, we should tidy that up and put it somewhere reusable if we're going to actually use it (lsst.utils.suppress_deprecation_warnings, or something).