Starting today, technical notes that you create with @sqrbot-jr create project will integrate with GitHub Actions for their continuous integration and delivery to LSST the Docs.
Advantages of GitHub Actions
Overall, you shouldn’t notice a significant difference while you author technotes. Your technote’s editions will still update soon after you push to GitHub, and your pull requests will still include feedback about whether your document builds successfully or not. On a closer look, GitHub Actions brings us significant advantages:
- Builds are blazing fast. Expect your LaTeX technote builds, which have traditionally been quite slow because of their Docker environment, to be quite snappy.
- More reliable. With our previous CI solution, we’ve started to see more and more failures for a push to trigger a build and for that build status to be reflected back in the PR. This was a major motivation for us to use GitHub Actions and we couldn’t be happier with the greater reliability.
- No more pull requests for encrypted credentials. Upload credentials for LSST the Docs are now stored as secrets with the associated GitHub organization. This means that you don’t need to remember to merge sqrbot’s pull request with encrypted upload credentials before your document appears on the web. For admins, this feature means it’s easier to rotate credentials.
In conjunction with this update, sqrbot-jr will now create new technotes with the GitHub repo’s description and homepage fields filled out.
Updating existing technical notes
The work that we’ve shipped today only affects new technical notes through updated templates, updates to the sqrbot-jr Slack bot, and Lander (the PDF landing page generator).
We intend to migrate all technical notes to GitHub Actions in the near future with automated PRs. If you feel inclined to skip the wait and migrate your technote yourself, you can do so. The steps are:
- Create a new file with the path
.github/workflows/ci.yaml:- For ReStructuredText technical notes, reference this sample:https://github.com/lsst/templates/blob/master/project_templates/technote_rst/testn-000/.github/workflows/ci.yaml Update the last line with your technote’s handle in lower-case.
- For LaTeX technical notes, reference this workflow: https://github.com/lsst/templates/blob/master/project_templates/technote_latex/testn-000/.github/workflows/ci.yaml Update the “lander” line. Again, case matters.
- Delete the
.travis.ymlfile. - Modify your README to reference GitHub Actions in the “links” section and in the build status badge (the
imagedirectives at the top). See the example README. Again, be sure to use your technote’s specific GitHub organization and repository name.
If you have any questions, feel free to ask in this forum topic on #dm-docs in Slack.