Prerequisites for using OTTR

If you wish to contribute to OTTR, please take a look at our Code of Conduct.

OTTR relies on R Markdown and GitHub Actions. You do not need to be an expert in either R Markdown or GitHub to get started as we will guide you through the process! However, we recommend spending a few minutes familiarizing yourself with both to gain a general understanding of their functionality before delving into our guide.

Please check out these resources if you are not familiar with R Markdown:

  • If you aren’t familiar with Markdown, this site is a nice introduction.

  • If you aren’t familiar with R Markdown (a variation of Markdown used here), you can find RStudio’s lessons here.

If you are not familiar with Git and GitHub, we recommend going through these chapters from our Reproducibility courses:

We offer two suggested approaches for creating content, based on your comfort and interest level in using Git and GitHub:

  • OTTR Entry Level: If you are not interested in delving into GitHub, you can use this version, which is entirely conducted through the GitHub web browser.
  • OTTR Advanced: If you are already familiar with Git and GitHub or have an interest in starting to use them, we suggest this method. It will involve some additional learning, but acquiring skills in Git and GitHub will be highly beneficial not only for OTTR but also for version control in various other contexts.

If you choose to use our OTTR Advanced guidance, you will need a method for working with Git.

If you do not have a method of working with Git already, we recommend using a Git client to facilitate easier branch management. Install GitKraken for a convenient way to handle your course locally.


Starting a new OTTR course

1. Create a repository from this template

On the landing page of this repository, locate the green “Use this template” in the upper right corner. Click on it and then “Create a new repository” to follow the provided instructions to configure your course’s GitHub repository.

*If you want to use OTTR Website or a different spin off go to that respective repository:

2. Name your repository and fill in a short description

Enter a name for your repository in the “Repository name” field and provide a brief description for it in the “Description” box.

3. Ensure your course is set to public for all GitHub Actions to work

When creating your repository, make sure to set it to a public repository.

In particular, the rendered preview on pull requests won’t work, but you can alternatively preview the content by re-rendering locally if you want to keep your course private. We will cover this later.

4. Select the Create repository from template button to proceed

After creating your repository, you will find that issues related to starting your course have been automatically generated and filed in your repository. To begin the setup process, navigate to the Issues tab and follow the instructions provided in those issues.

5. Add jhudsl-robot as a collaborator

*You can skip this step if your course is in the jhudsl organization.

To enable the full functionality of GitHub Actions in this repository, it is necessary to grant appropriate permissions. To achieve this, you should add jhudsl-robot as a collaborator to your repository with write permissions.

In your repository, go to your Settings > Collaborators & Teams and click on Add people. In the pop up window, search for and add jhudsl-robot.

If shown the option, choose the write option then click Add jhudsl-robot to this repository. Otherwise, just click add.

6. In personal repositories: check your settings

In case you have a personal repository or an organization that hasn’t utilized GitHub Actions previously, it is important to verify if workflow actions have been enabled.

Go to Settings and then Actions. Make sure that you have: 1. Given Read and write permissions 2. Checked Allow GitHub Actions to create and approve pull requests.

Then click Save.

7. Set up your GitHub personal access token

The OTTR robots require certain permissions to execute certain actions.

To give them permission for all the Actions, you need to set a GitHub Secret we will call GH_PAT. Go to Settings > Secrets and variables on the left side menu > Actions. On this page, scroll down to Repository secrets. Read more about GitHub Secrets here if you have general questions.

If you have organization admin privileges and plan on making multiple courses with OTTR, you can set GH_PAT as an organization secret so you don’t have to do this again. You only need to do this once as an organization (if this course is under jhudsl you don’t need to do this step).

  • Click New repository secret/New organization secret button.
  • Under Name, you must use GH_PAT.
  • For Secret: Create a personal access token following these instructions to create a “Classic” token (not a “Fine-grained token”). Underneath Select scopes, check both repo and workflow. Copy the Personal Access Token and save as a Secret in the repository that you made from our template.

All of your GitHub Actions should now be capable of running without any issues. If you encounter any problems, please report your issue to the main OTTR repository here.

8. Set up GitHub Pages

In your repository, go to Settings > Pages.

  • Under Source, pick Deploy fom a branch
  • Under Branch, pick main and /docs.
  • Then click Save.
  • Lastly, check the box that says Enforce HTTPS at the bottom of this page.

The URL for your material will be your main github pages url + / + your OTTR repository name and it will be displayed underneath your Settings > Pages.

By default, Github Pages is sent to a URL that looks like username.github.io where username is either your individual user name or your organization’s name. However, you can customize your GitHub Pages URL (like we have in this example here - jhudatascience.org). So it is likely your pages URL is something like username.github.io/your_ottr_repository_name.

For more information about GitHub Pages we recommend you refer to the GitHub documentation here.

Warning: If you go to your URL right now (before you’ve pushed any file changes) you might see a 404 error because nothing has been triggered to be rendered. You can check the URL after you file your first pull request (which we will guide you through in the next section.

9. Set up branch rules

* Don’t set these settings right away! Wait a few minutes after starting your repository.

Go to Settings > Branches and click Add branch protection rule. This is only possible if you have GitHub Pro, Team, or Enterprise access. We recommend seeing if your organization can give you access if you do not already have access. To get this access through your organization, you will need to transfer ownership of your repo to your organization. See here about how to do this.

For Branch name pattern, put main.

Protect the main branch:
Then check the box that says Require a pull request before merging.

* Note that if the user whose personal access token does not have admin privileges for step 6. Set up your GitHub personal access token, then you will need to skip this setting.

Make sure branches are updated:
- Check the box that says Require status checks to pass before merging. - Underneath this also check the box that says Require branches to be up to date before merging.

After setting up these new branch items, click Create and Save changes.

10. Enroll your repository for OTTR updates

This original course template (https://github.com/jhudsl/OTTR_Template) is always a work in progress. We are working on adding more features and smoothing out bugs as we go. This is also why your feedback is greatly appreciated.

When updates are made to files that aren’t specific to the course content but instead run checks and other processes in the original repository, pull requests are filed automatically to any downstream repositories made from this template.

To enroll in these automatic update pull requests, the new course’s repository name will need to be added to this file in the original template

  • Go to the respective file: .github/sync.yml of the OTTR template repository you created your repository from:
  • Add your repository’s name where it says #NEW REPO HERE#. Be careful to indent the same amount as the other repositories listed.
  • Click on Commit changes...
  • Type Add new repository to sync to Commit message.
  • Choose Create a new branch for this commit and start a pull request. Name the branch what you like.
  • Click Propose changes.
  • See this guide for any questions you have about creating a pull request from your forked repository.
  • Write a short pull request description describing that you are adding a new repository to the sync.yml file.
  • Click Create Pull Request
  • Request @cansavvy as a reviewer.

If your new course doesn’t need some of the functionality of these files or you find the automatic updates bothersome, you can feel free to use this guide to tailor which files you want updates for.

If you have any questions about the implications of any of these updates or files, please tag @cansavvy.


Methods of writing content

Again we have two recommended ways of writing content based on your comfort and interest level in using Git and GitHub:

Now you are ready to start writing content!