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

Create an RFC for change-controlled DM document Git branch and release policy

    Details

    • Type: Story
    • Status: Done
    • Resolution: Done
    • Fix Version/s: None
    • Component/s: Design Documents
    • Labels:
      None

      Description

      Wil, Frossie, Tim, and I have discussed a new change-controlled document Git repository workflow to replace the current policy (release on master, work on draft).

      The basic features of the new workflow are:

      • Development on master in ticket branches. In general, document development should mirror code development workflows.
      • Release branches (named after the corresponding RFC or LCR) that are never merged back to master.
      • The release manager backports commits on the release branches (amendments requested by a CCB) to the master branch.
      • Tags for docushare upload number and document version.
      • A moving tag for the docushare preferred version.

      These tags are an API for LSST the Docs (lsst.io) and for future DocuShare automation.

        Attachments

        1. doc-release-sketch.png
          414 kB
          Jonathan Sick
        2. document_workflow.pdf
          38 kB
          Jonathan Sick

          Issue Links

            Activity

            Hide
            tjenness Tim Jenness added a comment -

            This seems okay. I've already been using docushare-vNN tags so it would be great if we could continue to use those. Documents only get new versions at the end of the CCB process so there will be a version tag of some form corresponding to specific docushare versions that were approved. There will never be version numbers for unapproved documents. In theory you could use that scheme to work out which tag to show by default without a moving preferred tag.

            We do need to include a statement that if master is evolving but we need to make a minor change to a released version of the document, we would have to do that on a branch that may branch off the previous RFC branch rather than branching off master. Are we allowed to open the RFC before the document changes are complete, in order to know the branch name to use, or would we always use a DM ticket branch (since this is presumably work that has a JIRA ticket) before evolving into the RFC branch? (For project CCB you are allowed to obtain an LCR number before the work has been done).

            Show
            tjenness Tim Jenness added a comment - This seems okay. I've already been using docushare-vNN tags so it would be great if we could continue to use those. Documents only get new versions at the end of the CCB process so there will be a version tag of some form corresponding to specific docushare versions that were approved. There will never be version numbers for unapproved documents. In theory you could use that scheme to work out which tag to show by default without a moving preferred tag. We do need to include a statement that if master is evolving but we need to make a minor change to a released version of the document, we would have to do that on a branch that may branch off the previous RFC branch rather than branching off master. Are we allowed to open the RFC before the document changes are complete, in order to know the branch name to use, or would we always use a DM ticket branch (since this is presumably work that has a JIRA ticket) before evolving into the RFC branch? (For project CCB you are allowed to obtain an LCR number before the work has been done).
            Hide
            jsick Jonathan Sick added a comment -

            Attached is a sketch of the Git branching and tagging patterns we've envisioned.

            Features are:

            • docushare-1 tag created to kick off the release process. This tagged document is what the CCB initially reviews.
            • CCB-requested amendments happen on ticket branches that get merged into the tickets/RFC-N (or equivalent) release branch.
            • Another docushare-2 tag is created off the release branch for the CCB to review and approve.
            • A v1.0 semantic version tag is attached to the same commit as the approved DocuShare version.
            • The release manager cherry-picks the amendment commits on the tickets/RFC-N branch to master, where development is ongoing.

            LSST the Docs computes the preferred version of the document from the newest semantic version tag.

            Show
            jsick Jonathan Sick added a comment - Attached is a sketch of the Git branching and tagging patterns we've envisioned. Features are: docushare-1 tag created to kick off the release process. This tagged document is what the CCB initially reviews. CCB-requested amendments happen on ticket branches that get merged into the tickets/RFC-N (or equivalent) release branch. Another docushare-2 tag is created off the release branch for the CCB to review and approve. A v1.0 semantic version tag is attached to the same commit as the approved DocuShare version. The release manager cherry-picks the amendment commits on the tickets/RFC-N branch to master , where development is ongoing. LSST the Docs computes the preferred version of the document from the newest semantic version tag.
            Hide
            tjenness Tim Jenness added a comment -

            Are we going to add a semantic version tag to current LDMs so that LtD will do the right thing next time they get edited?

            docushare-v1 would be better than docushare-1 in the sense that all the existing documents would then be using the right scheme.

            I'd still like a statement on how to do a minor change to LDM whilst larger rewriting is ongoing.

            Show
            tjenness Tim Jenness added a comment - Are we going to add a semantic version tag to current LDMs so that LtD will do the right thing next time they get edited? docushare-v1 would be better than docushare-1 in the sense that all the existing documents would then be using the right scheme. I'd still like a statement on how to do a minor change to LDM whilst larger rewriting is ongoing.
            Hide
            jsick Jonathan Sick added a comment -

            The document_workflow.pdf attachment has draft copy for the DM document workflow.

            I think the best approach for the RFC is to put this text on a ticket branch in the DM Developer Guide, include illustrated examples of git commit trees at each phase, and then create an RFC that points to the ticket branch draft. I think this will minimize confusion about what our proposed workflow is.

            Show
            jsick Jonathan Sick added a comment - The document_workflow.pdf attachment has draft copy for the DM document workflow. I think the best approach for the RFC is to put this text on a ticket branch in the DM Developer Guide, include illustrated examples of git commit trees at each phase, and then create an RFC that points to the ticket branch draft. I think this will minimize confusion about what our proposed workflow is.
            Hide
            jsick Jonathan Sick added a comment -

            The proposed document at https://developer.lsst.io/v/DM-11952/docs/change-controlled-docs.html is, I think, ready to bring to RFC. I've included all of Tim Jenness's suggestion from the PR (https://github.com/lsst-dm/dm_dev_guide/pull/169).

            Unless anyone brings up any issues this morning, I'll create an RFC around this document later today and any remaining comments can occur at that stage.

            Show
            jsick Jonathan Sick added a comment - The proposed document at https://developer.lsst.io/v/DM-11952/docs/change-controlled-docs.html is, I think, ready to bring to RFC. I've included all of Tim Jenness 's suggestion from the PR ( https://github.com/lsst-dm/dm_dev_guide/pull/169 ). Unless anyone brings up any issues this morning, I'll create an RFC around this document later today and any remaining comments can occur at that stage.
            Hide
            jsick Jonathan Sick added a comment - - edited

            With RFC-401 adopted, time for formal ticket review.

            Show
            jsick Jonathan Sick added a comment - - edited With RFC-401 adopted, time for formal ticket review.
            Hide
            jsick Jonathan Sick added a comment -

            Tim Jenness, can you give the final sign-off for this ticket review?

            I have the engineering update to LSST the Docs in review over at DM-12356, so I think we're just about to ship the new release policy.

            Show
            jsick Jonathan Sick added a comment - Tim Jenness , can you give the final sign-off for this ticket review? I have the engineering update to LSST the Docs in review over at DM-12356 , so I think we're just about to ship the new release policy.
            Hide
            tjenness Tim Jenness added a comment -

            I'm sorry. I had forgotten I was reviewing this. Thanks for making the changes. Looks good.

            Show
            tjenness Tim Jenness added a comment - I'm sorry. I had forgotten I was reviewing this. Thanks for making the changes. Looks good.

              People

              • Assignee:
                jsick Jonathan Sick
                Reporter:
                jsick Jonathan Sick
                Reviewers:
                Tim Jenness
                Watchers:
                Frossie Economou, John Swinbank, Jonathan Sick, Tim Jenness, Wil O'Mullane
              • Votes:
                0 Vote for this issue
                Watchers:
                5 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:

                  Summary Panel