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

Revised DM change-controlled document release workflow

    Details

    • Type: RFC
    • Status: Implemented
    • Resolution: Done
    • Component/s: DM
    • Labels:
      None

      Description

      I propose a new workflow for DM's Git-based change-controlled documents. This applies to DM's internal change-controlled documents (LDM and DMTR) and how we contribute to project-level documents (such as LPM and LSE).

      For context, our current workflow has relied upon the master branch representing the baselined document. Writing and review has been done on a draft branch. Because this workflow is distinct from how we develop code, it presents unnecessary friction for those writing change-controlled documents.

      This proposal designates the master branch as the integration branch, like it is for our software development. Releases happen on release branches named after the associated RFC or LCR. I have written the proposed workflow in detail in this draft document: https://developer.lsst.io/v/DM-11952/docs/change-controlled-docs.html

      Implementing this RFC will involve:

      • Merging the DM-11952 branch in the Developer Guide.
      • Updating LSST the Docs so that it recognizes document version tags and displays the most recent baselined version as the document's <handle>.lsst.io landing page.
      • Re-arranging any document Git repositories that have active draft branches.

        Attachments

          Issue Links

            Activity

            Hide
            jsick Jonathan Sick added a comment - - edited

            In the draft (see also the GitHub PR) I've made these improvements based on feedback:

            • Improved wording in the introduction and created a section specifically to talk about formats.
            • Resolved the LDM vs LPM/LSE discussion by deferring LPM-51. It says that LDMs are subsystem controlled and LSE/LPM is project controlled.
            • Indicate that an RFC must be filed to alter the change-controlled document workflow rather than putting it squarely on the Software Architect.

            Discussions that are unresolved:

            • In step 4 of Releasing a new version from the master branch we say that a ticket may not be needed to fix minor feedback from a CCB (like a single typo) can happen directly on the release branch. Tim Jenness wants this flexibility but John Swinbank wants every commit to be in a ticket branch. Do any stakeholders who regularly manage change-controlled documents have a preference here? I can see the benefit of mandatory ticket branches because they eliminate the possibility of pushing a broken document to a release branch and thus prompting either a fix+rebase or just a fix commit. Maybe we can just state that "code review" is not necessary for these types of tickets?
            • We haven't resolved how to concretely name the people who process DocuShare uploads for DM (in the section Uploading to DocuShare). Part of the issue is that we'll soon have a release manager who may be substantially involved in this process, and despite being named the DM documentalist in LDM-294 I don't actually possess full DocuShare upload permissions (yet)! Here's my proposal:
              • We create a dedicated Slack channel called #dm-docushare.
              • The documented workflow says to send upload requests (and even drag/drop Word docs) into that Slack channel.
              • Then team member processes that request.

            I like this Slack-based workflow because it provides management flexibility to assign people to this task without having to burden this particular document with resource assertions. And to boot, Slack messaging is likely a more robust workflow than emailing documents to a single person.

            If I can get definitive feedback on these two issues I can think we can adopt this RFC shortly.

            Show
            jsick Jonathan Sick added a comment - - edited In the draft (see also the GitHub PR ) I've made these improvements based on feedback: Improved wording in the introduction and created a section specifically to talk about formats. Resolved the LDM vs LPM/LSE discussion by deferring LPM-51. It says that LDMs are subsystem controlled and LSE/LPM is project controlled. Indicate that an RFC must be filed to alter the change-controlled document workflow rather than putting it squarely on the Software Architect. Discussions that are unresolved: In step 4 of Releasing a new version from the master branch we say that a ticket may not be needed to fix minor feedback from a CCB (like a single typo) can happen directly on the release branch. Tim Jenness wants this flexibility but John Swinbank wants every commit to be in a ticket branch. Do any stakeholders who regularly manage change-controlled documents have a preference here? I can see the benefit of mandatory ticket branches because they eliminate the possibility of pushing a broken document to a release branch and thus prompting either a fix+rebase or just a fix commit. Maybe we can just state that "code review" is not necessary for these types of tickets? We haven't resolved how to concretely name the people who process DocuShare uploads for DM (in the section Uploading to DocuShare ). Part of the issue is that we'll soon have a release manager who may be substantially involved in this process, and despite being named the DM documentalist in LDM-294 I don't actually possess full DocuShare upload permissions (yet)! Here's my proposal: We create a dedicated Slack channel called #dm-docushare . The documented workflow says to send upload requests (and even drag/drop Word docs) into that Slack channel. Then team member processes that request. I like this Slack-based workflow because it provides management flexibility to assign people to this task without having to burden this particular document with resource assertions. And to boot, Slack messaging is likely a more robust workflow than emailing documents to a single person. If I can get definitive feedback on these two issues I can think we can adopt this RFC shortly.
            Hide
            swinbank John Swinbank added a comment - - edited

            Improved wording in the introduction and created a section specifically to talk about formats

            . Well, I still don't like "recommending" LaTeX, because I don't substantively know what that's supposed to mean. But this is just quibbling on my part.

            Resolved the LDM vs LPM/LSE discussion by deferring LPM-51. It says that LDMs are subsystem controlled and LSE/LPM is project controlled.

            The point here is that LPM-51 is contradictory. While you're correct in quoting §5.2, the same document also says "typically, Project-level controlled documents have LPM or LSE handles; however, there are some cases in which documents with LDM or other handles have been placed under project-level change control". While clearly LPM-51 is at fault here, I suggest our documentation should avoid the issue altogether: just punt all questions about document handle to LPM-51 (and, for bonus points, file a ticket requesting that it be made consistent).

            Indicate that an RFC must be filed to alter the change-controlled document workflow rather than putting it squarely on the Software Architect.

            we say that a ticket may not be needed to fix minor feedback from a CCB (like a single typo)

            If the wording can be updated to indicate that "minor feedback" means typo fixing, then I'm happy for that to go directly on master. I'm worried that the interpretation of "minor" is very subjective, and there must be no wriggle room for doing any sort of substantial work without a ticket.

            We haven't resolved how to concretely name the people who process DocuShare uploads for DM...

            I like the Slack workflow described.

            Beyond that, I find myself a bit confused by the discussion about documentalists and librarians. If the description in LDM-294 is incorrect or misleading, please file a ticket suggesting how it can be corrected. (Even if we can sidestep the issue in this particular documentation through use of Slack, clever wording, etc, we should also fix LDM-294).

            Show
            swinbank John Swinbank added a comment - - edited Improved wording in the introduction and created a section specifically to talk about formats . Well, I still don't like "recommending" LaTeX, because I don't substantively know what that's supposed to mean. But this is just quibbling on my part. Resolved the LDM vs LPM/LSE discussion by deferring LPM-51. It says that LDMs are subsystem controlled and LSE/LPM is project controlled. The point here is that LPM-51 is contradictory. While you're correct in quoting §5.2, the same document also says "typically, Project-level controlled documents have LPM or LSE handles; however, there are some cases in which documents with LDM or other handles have been placed under project-level change control". While clearly LPM-51 is at fault here, I suggest our documentation should avoid the issue altogether: just punt all questions about document handle to LPM-51 (and, for bonus points, file a ticket requesting that it be made consistent). Indicate that an RFC must be filed to alter the change-controlled document workflow rather than putting it squarely on the Software Architect. we say that a ticket may not be needed to fix minor feedback from a CCB (like a single typo) If the wording can be updated to indicate that "minor feedback" means typo fixing, then I'm happy for that to go directly on master. I'm worried that the interpretation of "minor" is very subjective, and there must be no wriggle room for doing any sort of substantial work without a ticket. We haven't resolved how to concretely name the people who process DocuShare uploads for DM... I like the Slack workflow described. Beyond that, I find myself a bit confused by the discussion about documentalists and librarians. If the description in LDM-294 is incorrect or misleading, please file a ticket suggesting how it can be corrected. (Even if we can sidestep the issue in this particular documentation through use of Slack, clever wording, etc, we should also fix LDM-294).
            Hide
            ktl Kian-Tat Lim added a comment -

            I'm not sure if I know of any LDM documents that have been placed under project-level change control. I do know that some other subsystem-level documents have been promoted to LSEs to get them under project-level change control. The flawed definition appears to have been added to LPM-51 in the very last revision between 2017-07-01 and 2017-07-06 (which was supposedly only to address Richard Dubois' comments).

            Show
            ktl Kian-Tat Lim added a comment - I'm not sure if I know of any LDM documents that have been placed under project-level change control. I do know that some other subsystem-level documents have been promoted to LSEs to get them under project-level change control. The flawed definition appears to have been added to LPM-51 in the very last revision between 2017-07-01 and 2017-07-06 (which was supposedly only to address Richard Dubois' comments).
            Hide
            jsick Jonathan Sick added a comment -

            All issues should be resolved, or be in the process of being resolved.

            Show
            jsick Jonathan Sick added a comment - All issues should be resolved, or be in the process of being resolved. I have emailed Robert McKercher to clarify the LPM-51 issue with LDMs. Meanwhile, I removed any mapping between handles and change-control boards . I introduced the #dm-docushare slack channel to facilitate DocuShare uploads and document creation. I filed DM-12304 to have the DM documentalist role clarified/updated in LDM-294. I qualified the circumstances to use Word: "When individuals responsible for writing and maintaining a document are uncomfortable with LaTeX and Git. / When a document contains "Sensitive" or "Highly Sensitive" information (per `LPM-51`_ §2)." I clarified language around making amendments on a release branch .
            Hide
            jsick Jonathan Sick added a comment -

            Adopting this RFC since it seems that there are no blocking issues. Implementation tickets are DM-11952 (the workflow document) and DM-12356 (support from LSST the Docs).

            Show
            jsick Jonathan Sick added a comment - Adopting this RFC since it seems that there are no blocking issues. Implementation tickets are DM-11952 (the workflow document) and DM-12356 (support from LSST the Docs).

              People

              • Assignee:
                jsick Jonathan Sick
                Reporter:
                jsick Jonathan Sick
                Watchers:
                Donald Petravick, Frossie Economou, John Swinbank, Jonathan Sick, Kian-Tat Lim, Tim Jenness, Wil O'Mullane, Xiuqin Wu [X] (Inactive)
              • Votes:
                0 Vote for this issue
                Watchers:
                8 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:
                  Planned End:

                  Summary Panel