Details
-
Type:
Story
-
Status: Done
-
Resolution: Done
-
Fix Version/s: None
-
Component/s: Design Documents
-
Labels:None
-
Story Points:4.8
-
Epic Link:
-
Team:SQuaRE
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
Issue Links
Activity
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.
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.
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.
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.
With RFC-401 adopted, time for formal ticket review.
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.
I'm sorry. I had forgotten I was reviewing this. Thanks for making the changes. Looks good.
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).