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
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
- 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
- Modify your README to reference GitHub Actions and use its badge. See this diff on GitHub for guidance.
If you have any questions, feel free to ask in this forum topic on #dm-docs in Slack.