The care and keeping of OTTR (a guide to maintenance)

[cansavvy]

A summary of the OTTR ecosystem:

1. The ottrpal R package has the direct functionality (stored in
2. jhudsl/base_ottr and jhudsl/ottrpal docker images have the ottrpal R package
   • base_ottr has the essentials for running OTTR
   • jhudsl/ottrpal is just an executable version of base_ottr
3. These docker images are used in the GitHub Actions ottr-reports and ottr-preview
4. The GitHub Actions are used by the workflows in the templates: OTTR_Template, OTTR_Quarto, OTTR_Template_Website, and OTTR_Quarto_Website.
5. These template repos send out syncs to users' individual ottr courses and websites.

How to make changes/add features to ottr

1. Start with the ottrpal R package and test things on the relevant template locally.
   • Create a new branch on ottrpal, take a look at the unit tests set up in the testthat folder. You can run these for initial testing.
   • You can also load your dev version of ottrpal and then test your changes on a local OTTR course/website. Either a template or a real course/website.
   • File a pull request to ottrpal, make sure the tests pass and have it reviewed but then you can merge
2. Now go to ottr-docker and push a development version of the docker images jhudsl/base_ottr:dev and jhudsl/ottrpal:dev
   3a. If needed, make associated changes to ottr-reports or ottr-preview on a development branch (DO NOT merge yet).
   • There are tests that will run on these repos
     3b. At the same time you have ottr-reports or ottr-preview branch open, go to a relevant template repository and open a development branch there to test. You will need to change references in the relevant workflow to call your development branch to test your new changes ottrproject/ottr-reports@dev_branch_name temporarily.
   • You may need return to make updates to the ottrpal R package and docker images to make adjustments in this process.
3. Once everything is working and all tests are passing, you can begin the merging process.

If NO changes are need to users workflows then you can just in this order:

1. Change tag of docker image jhudsl/base_ottr:dev -> to jhudsl/base_ottr:mainand push to dockerhub (See ottr-docker README for how to do this)
2. Change tag of docker image jhudsl/ottrpal:dev -> to jhudsl/ottrpal:main and push to dockerhub
3. On your development branch change ottr-reports or ottr-previews references to reference the docker images with main tags jhudsl/ottrpal:main. Ensure tests are still passing.
4. Merge ottr-reports or ottr-previews to main (this will now make the changes live to users).
5. Yay! You're good. Just keep an eye out for breaks.

If this involves changes to user workflows then there are extra steps.

6. Create a new release of OTTR See examples here https://github.com/ottrproject/OTTR_Template/tags
7. Send out an OTTR sync and post a discussion with the explanation of the steps.
8. Be cognizant of the downstream templates and OTTR variants that may need slightly different versions of these changes.

OTTR Sleuthing tips

Get the logs

Navigate to the specific repo that is having the problem. Read the GitHub Action logs extensively. You may need to go to a step that is not automatically dropped down when you open it.

Read the logs

Look for steps called Run the check.

Try to replicate the error

Use the appropriate template repo to file a draft PR to try to replicate the error. OTTR_Template/OTTR_Quarto

Document it all

Document the error and a suggested fix as a GitHub issue now you can address it by following the steps above.