Uploaded image for project: 'Request For Comments'
  1. Request For Comments
  2. RFC-659

Update deprecation procedure to avoid generating warnings from LSST code

    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

            Hide
            swinbank John Swinbank added a comment -

            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).

            Show
            swinbank John Swinbank added a comment - 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).
            Hide
            krzys Krzysztof Findeisen added a comment - - edited

            Whether or not this RFC gets approved, I think that would be a very useful tool.

            Show
            krzys Krzysztof Findeisen added a comment - - edited Whether or not this RFC gets approved, I think that would be a very useful tool.
            Hide
            ktl Kian-Tat Lim added a comment -

            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.

            Show
            ktl Kian-Tat Lim added a comment - 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.
            Hide
            swinbank John Swinbank added a comment -

            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.

            Show
            swinbank John Swinbank added a comment - 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.
            Hide
            swinbank John Swinbank added a comment -

            Oh, worth adding: on DM-23239, I've deliberately not addressed the C++ deprecation issue that Jim Bosch refers to above; I think it's appropriate for those with more expertise in that than I to deal with that on DM-21712.

            Show
            swinbank John Swinbank added a comment - Oh, worth adding: on DM-23239 , I've deliberately not addressed the C++ deprecation issue that Jim Bosch refers to above; I think it's appropriate for those with more expertise in that than I to deal with that on DM-21712 .

              People

              • Assignee:
                swinbank John Swinbank
                Reporter:
                swinbank John Swinbank
                Watchers:
                Eli Rykoff, Gabriele Comoretto, Jim Bosch, John Parejko, John Swinbank, Kian-Tat Lim, Krzysztof Findeisen, Tim Jenness
              • Votes:
                0 Vote for this issue
                Watchers:
                8 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Planned End:

                  Summary Panel