To request changes to these standards, file an RFC.
Writing change-controlled documentation¶
Change-controlled documents require approval from a Change Control Board (CCB) before they can be released. Data Management documents must be approved by the DM CCB using the RFC process (see LDM-294). Project-level documents must be approved by the Project CCB. Overall, the project-wide change control process is described in LPM-19 and the process for managing documents is described in LPM-51.
This page describes the specific development and release processes for change-controlled documents produced by DM:
- Document formats
- Drafting workflow
- Releasing a new version from the master branch
- Hotfixing a released document
Additional subprocedures and references:
Change controlled documents can be written as Word documents or as LaTeX projects in GitHub repositories. Requirements documents are special and are generated from MagicDraw.
LaTeX is the preferred format for DM documents. Reasons to create a Word document instead are:
- 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).
LaTeX documents must use the lsstdoc document class provided by the lsst-texmf package. The source content for LaTeX documents must be managed by Git and hosted in the LSST organization on GitHub (https://github.com/lsst). A document’s GitHub repository is named after the document’s handle (see https://github.com/lsst/LDM-151 for example).
The project’s template for Word documents is available as Document-9224 in DocuShare. Due to their nature, Word documents are not managed in Git repositories. The release process described on this page is explicitly for Git-based documents, but the principles still apply (DM’s Git-based release workflow is compatible with the project’s general workflow described in LPM-51). Where the release procedure calls for a DocuShare upload, provide both the rendered PDF and the original Word file to the DM documentalist.
LPM-51 recommends that draft documents always be uploaded to DocuShare at least every three months if there are draft changes. This guideline is especially important for Word documents that do not benefit from GitHub’s collaborative features.
Requirements are added to the PSE or DM models in MagicDraw. DM Systems Engineering is responsible for doing this. New requirements should be submitted to DM SE using a spreadsheet with these columns: ID, title, specification, discussion, priority.
When editing or adding requirements, the following checklist may be of assistance:
- Check that the requirement ID doesn’t conflict with other branches (especially if auto-generated)
- Prefix package and requirement titles with a number to control ordering where needed
- Prefer non-HTML text fields if no formatting is required
- Specification goes in main text, no bold “Specification:” lead-in
- Discussion goes in documentation text, no bold “Discussion:” lead-in
- Check that numeric values are in parameters and properly linked
- Check that priority is set (mandatory for LSE-61)
- Check that flowdown from higher-level requirements (e.g. LSE-30) is present where appropriate
- Inform (Project or DM) SE to add verification elements
Write change-controlled documents using DM’s standard workflow. That is:
- Create a ticket branch from
- Work on the ticket branch.
- Have the ticket peer-reviewed.
- Rebase and merge the ticket branch to
master does not denote acceptance by a CCB.
Instead, it adds to the changeset that will be included in the next CCB review (see next).
Releasing a new version from the master branch¶
Follow these steps to submit a document to the CCB and release a new baselined version:
Check out the head of the
masterbranch and follow the procedure in Uploading to DocuShare.
You can get the PDF for the DocuShare upload either by building the document locally or downloading it from the document’s landing page at
Submit a request to the CCB. The procedure depends on the CCB:
Create a release branch based off the same commit as the DocuShare tag:
For a project document:
git checkout -b tickets/LCR-<N> git push -u
For a DM document:
git checkout -b tickets/RFC-<N> git push -u
<N>with the LCR or RFC number.
When the CCB responds, they may ask for changes. In general, use a ticket branch to address these changes. Multiple people may address separate sets of requests in parallel with multiple ticket branches. Merge these ticket branches back into the release branch. For example:
git checkout tickets/RFC-<N> git checkout -b tickets/DM-<M> # edit and commit git checkout tickets/RFC-<N> git pull git checkout tickets/DM-<M> git rebase -i tickets/RFC-<N> git checkout tickets/RFC-<N> git merge --no-ff tickets/DM-<M>
For extremely minor changes (on the scale of a typo), you may commit directly to the release branch rather than create a JIRA ticket. Exercise caution not to push a commit that breaks the LaTeX build (you may not revert a commit already pushed to a release branch on GitHub).
When the issues are addressed, notify the CCB:
- For a project document, create a new DocuShare upload and notify the CCB.
- For a DM document, create a comment on the RFC confirming the changes and link to the
https://<handle>.lsst.io/v/RFC-<n>landing page for the release branch. You don’t need to create intermediate DocuShare versions for the DM CCB.
Repeat this step for each round of CCB feedback.
When the CCB approves the document, create a release:
Make two commits to the head of the release branch. In the first commit:
- Update document’s change record. The Project librarian or DM release manager, through the CCB, determines the document’s semantic version.
In the second commit:
- Remove the
lsstdraftoption from the document class.
- Set the
\datecommand using a YYYY-MM-DD format.
Create a new DocuShare upload. At this stage, the Project librarian will review the change record’s content (for project documents). If changes are needed, repeat the previous step and this one.
Once the Project librarian or DM documentalist has uploaded the document and made it the new preferred version, create a semantic version tag at the same commit as the DocuShare tag:
git tag -a v<major>.<minor> git push --tags
In your command, replace
<major>.<minor>with the semantic version.
Format the Git tag message as:
The URL should point to the DocuShare version (same as the DocuShare tag you created in step 5.2 above).
Backport the amendment commits made on the release branch back to the
Create a user branch from the
git checkout master git checkout -b u/<username>/v<major>.<minor>-backport
Cherry-pick commits from the release branch onto the new backport branch. For example:
git cherry-pick <commit-sha>
Do not backport the commit that removed the
lsstdraftoption and set the
Push the backport branch to GitHub for continuous integration validation, rebase, and merge to master. For example:
git checkout master git pull git checkout u/<username>/v<major>.<minor>-backport git rebase -i master git push -u # --force git checkout master git merge --no-ff u/<username>/v<major>.<minor>-backport git push
Hotfixing a released document¶
The procedure above (Releasing a new version from the master branch) describes how to make a new version of a document from the
Sometimes it is necessary to hotfix a released document to fix a typo or make a similar minor change.
In these cases you may not want to make a new release from the
master branch because
master has substantive, and unrelated, new content.
Instead, you may hotfix a document from the release branch.
If no changes have been merged to
master since the document was released, you can follow the regular procedure for Releasing a new version from the master branch.
Follow these steps to hotfix a document:
Check out the head of the release branch for the version being fixed:
For a project document:
git checkout tickets/LCR-<prev>
For a DM document:
git checkout tickets/RFC-<prev>
<prev>is the RFC or LCR number of the document release being fixed.
Create a ticket branch (the JIRA ticket is scoped for implementing the fix and coordinating the release):
git checkout -b tickets/DM-<N> git push -u
Commit fixes onto that
tickets/DM-<N>branch and push to GitHub.
Follow the steps in Releasing a new version from the master branch, noting that the base branch is now
master. In the last step, the amendment commits (such as those on the
tickets/DM-<N>branch and on the release branch) are still backported to
master. The hotfix release branch is not merged onto the previous release branch.
Summary of the Git tag and branch API¶
In the change-controlled documentation Git workflow, branches and tags form an API that is used by DM’s infrastructure to automate documentation management. This section summarizes the intents of each type of branch and tag.
Submissions to the DM CCB have an associated RFC and submissions to the Project CCB have an associated LCR.
Work related to a release is done on a release branch named after the RFC or LCR number:
These release branches are never merged back to the
Instead, amendments are backported to
master using git cherry-pick.
Note that because creating an RFC or LCR requires a document in DocuShare, release branches are only created after the initial DocuShare tag is created.
master branch is the main development branch where individual ticket branches are integrated.
The document on the
master branch is understood to be peer-reviewed but not baselined by the CCB.