Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-9844

Engineer and document a technote deprecation process

    Details

      Description

      Design a technote deprecation process, engineer it, and document it.

      The process was sketched for DMTN-026:

      1. In metadata.yaml add these fields:

      deprecation:
        date: 2017-03-16
        message: >-
          A sentence or two explaining the deprecation.
        replacements:
          - {"name": "DM Developer Guide: Python wrappers for C++ with pybind11", "url": "https://developer.lsst.io/coding/python_wrappers_for_cpp_with_pybind11.html"}
      

      2. At the top of your index.rst, but below the :tocdepth: 1, including a warning directive:

      .. warning::
       
         A sentence or two explaining the deprecation.
       
         Date deprecated: 2017-03-16.
       
         Replacement links:
       
         - `DM Developer Guide: Python wrappers for C++ with pybind11 <https://developer.lsst.io/coding/python_wrappers_for_cpp_with_pybind11.html>`_
      

      Engineering notes:

      • Make it so that only (1) or (2) are needed to officially deprecate a technote.
      • Add a `canonical-url` header into deprecated technotes pointing to a replacement link so that Google will prefer the replacement URL over offering a deprecated document.

        Attachments

          Issue Links

            Activity

            Hide
            tjenness Tim Jenness added a comment -

            Just a note that DMTN-024 (DM-9466) needs to have it's deprecation record updated to match this standard.

            Show
            tjenness Tim Jenness added a comment - Just a note that DMTN-024 ( DM-9466 ) needs to have it's deprecation record updated to match this standard.
            Hide
            jsick Jonathan Sick added a comment -
            Show
            jsick Jonathan Sick added a comment - Also deprecate https://github.com/lsst-dm/dmtn-054  ( Krzysztof Findeisen )
            Hide
            tjenness Tim Jenness added a comment -

            I feel strongly that deprecated documents should still include the original content along with a big deprecation notice. DMTN-054 currently just says "this is deprecated". I don't think we should always rely on the full git history being around. I could change my mind if we are permanently archiving the previous version with a DOI and the deprecated version knows about it. The deprecation notice should also include a reason along with a pointer, if relevant, to a replacement document.

            I think this implies that there needs to be a "deprecated" class option for latex files so that a big deprecation banner can be included similarly as we use for "draft".

            Show
            tjenness Tim Jenness added a comment - I feel strongly that deprecated documents should still include the original content along with a big deprecation notice. DMTN-054 currently just says "this is deprecated". I don't think we should always rely on the full git history being around. I could change my mind if we are permanently archiving the previous version with a DOI and the deprecated version knows about it. The deprecation notice should also include a reason along with a pointer, if relevant, to a replacement document. I think this implies that there needs to be a "deprecated" class option for latex files so that a big deprecation banner can be included similarly as we use for "draft".
            Hide
            jsick Jonathan Sick added a comment - - edited

            I feel strongly that deprecated documents should still include the original content along with a big deprecation notice.

            I do fully agree with that. In that case an author scrubbed both the content and the title. I put the title back so it wouldn't raise red flags for me on the www.lsst.io page (I was looking through it over the weekend and through the build had broken). I just haven't put the content back (yet). But I like your idea (keeping the content or archiving with a DOI.

            I think we can incorporate all those features into a deprecation process.

            Show
            jsick Jonathan Sick added a comment - - edited I feel strongly that deprecated documents should still include the original content along with a big deprecation notice. I do fully agree with that. In that case an author scrubbed both the content and the title. I put the title back so it wouldn't raise red flags for me on the www.lsst.io  page (I was looking through it over the weekend and through the build had broken). I just haven't put the content back (yet). But I like your idea (keeping the content or archiving with a DOI. I think we can incorporate all those features into a deprecation process.
            Hide
            krzys Krzysztof Findeisen added a comment - - edited

            In this case, the author scrubbed the content to avoid it getting published on https://www.lsst.io/ (particularly since it had never been "published" out of draft status). If the site doesn't publish docs that are marked as deprecated in their metadata, then I have no objections to keeping the text.

            I would object to unfinished documents getting officially DOIed.

            Show
            krzys Krzysztof Findeisen added a comment - - edited In this case, the author scrubbed the content to avoid it getting published on https://www.lsst.io/ (particularly since it had never been "published" out of draft status). If the site doesn't publish docs that are marked as deprecated in their metadata, then I have no objections to keeping the text. I would object to unfinished documents getting officially DOIed.

              People

              • Assignee:
                jsick Jonathan Sick
                Reporter:
                jsick Jonathan Sick
                Watchers:
                Jonathan Sick, Krzysztof Findeisen, Tim Jenness
              • Votes:
                0 Vote for this issue
                Watchers:
                3 Start watching this issue

                Dates

                • Created:
                  Updated:

                  Summary Panel