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