generated from jhudsl/OTTR_Template_Website
-
Notifications
You must be signed in to change notification settings - Fork 1
/
getting_started.Rmd
202 lines (124 loc) · 15.5 KB
/
getting_started.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
---
title: "Getting started"
output:
html_document:
toc: true
toc_float: true
---
There are two main types of OTTR websites:
- [OTTR Website classic](https://github.com/jhudsl/OTTR_Template_Website) - this is your typical website like the one you are looking at right now, with a nav bar on the top. Keep in mind you can customize everything without too much effort -- our guide will hopefully help!
- [OTTR Course Website](https://github.com/jhudsl/OTTR_Template) - this is for books/courses and has a table of contents on the side.
<img src="resources/images/ottr-course-example.png" width = 400>
## Prerequisites for using OTTR
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. Note that OTTR is also compatible with Quarto and regular markdown websites.
- If you aren't familiar with **Markdown**, this [site](https://www.markdownguide.org/getting-started/) 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](https://rmarkdown.rstudio.com/lesson-1.html).
If you are not familiar with **Git and GitHub**, we recommend going through these chapters from our Reproducibility courses:
- [Making your project open source with GitHub](https://jhudatascience.org/Reproducibility_in_Cancer_Informatics/making-your-project-open-source-with-github.html)
- [Using version control with GitHub](https://jhudatascience.org/Adv_Reproducibility_in_Cancer_Informatics/using-version-control-with-github.html)
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](https://www.gitkraken.com/) for a convenient way to handle your course locally.
***
## Starting a new OTTR website/course
### 1. Create a repository from this template
On the [landing page of the OTTR Website repository](https://github.com/jhudsl/OTTR_Template_Website) or the [OTTR Course repository](https://github.com/jhudsl/OTTR_Template) 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.
### 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](https://docs.github.com/en/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility).
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. Check your repository GitHub Action 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`.
<img src="https://github.com/jhudsl/ottr-website/raw/main/resources/images/workflow-permissions.png" width = 500>
### 6. 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](https://docs.github.com/en/actions/security-guides/encrypted-secrets) 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](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) 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](https://github.com/jhudsl/OTTR_Template/issues/new?assignees=&labels=bug&projects=&template=course-problem-report.md&title%5B%5D=Problem).
### 7. Set up GitHub Pages
You'll need to set this up so that your website or course will be published to a URL!
In your repository, go to `Settings` > `Pages`.
- Under `Source`, pick `Deploy fom a branch`
- Under `Branch`, pick `main` and choose `/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](https://docs.github.com/en/pages/quickstart).
<p class="comment">
**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](https://github.com/jhudsl/OTTR_Template/wiki/Start-editing-your-course).
</p>
### 8. Enroll your repository for OTTR updates (Not required but highly encouraged)
These OTTR templates (https://github.com/jhudsl/OTTR_Template_Website or https://github.com/jhudsl/OTTR_Template) are 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](https://github.com/jhudsl/OTTR_Template/issues/new/choose).
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 the relevant OTTR template sync file. See [Which file should you edit section for links to the file you want](#which-sync-file-should-you-edit)**
If you're a member of the jhudsl GitHub organization, you can make edits to the sync file in a new branch and open a pull request.
If you're not a member of the jhudsl GitHub organization, you can use one of these alternatives:
* Submit a response in our [OTTR Feedback Google Form](https://forms.gle/jGQnd5oemHWyuUq28) by providing the information for your new repo (organization or username as well as the new repo name) in the "Do you have any overall suggestions for OTTR?" question and we can make edits to the `sync.yml` file for you.
* Open an issue in the relevant repo [(links in table below)](#links-to-open-an-issue-in-an-ottr-template-repository) providing us the information about your repo (organization or username as well as the new repo name) and we can make edits to the `sync.yml` file for you.
* Edit the sync file by creating a fork and opening a pull request from that fork. We provide instructions for that below [in the section Making edits to these files if you are not part of the jhudsl Github organization](#making-edits-to-this-file-if-you-are-not-part-of-the-jhudsl-github-organization).
#### Which sync file should you edit?
- Go to the respective file: `.github/sync.yml` of the OTTR template repository you created your repository from:
- [File for the main course OTTR_Template updates](https://github.com/jhudsl/OTTR_Template/blob/main/.github/sync.yml)
- [File for the website OTTR_Template_Website updates](https://github.com/jhudsl/OTTR_Template_Website/blob/main/.github/sync.yml)
- [File for the OTTR_Quizzes updates](https://github.com/jhudsl/OTTR_Quizzes/blob/main/.github/sync.yml)
#### Making edits to this file if you are not part of the jhudsl GitHub organization
If you're not part of the jhudsl GitHub organization, to edit the `sync.yml` file you'll need to
- fork the repo
- make the changes (described below) to `sync.yml`, committing them to a branch
- create a PR in the original OTTR repo using your branch
Detailed instructions for these steps are provided below:
- Click the pencil in the upper right for "Fork this repository and edit the file"
- Click the green button that says "Fork this repository"
- Make the edits to the file, adding your repository's name where it says `#NEW REPO HERE#`. Be careful to indent the same amount as the other repositories listed.
- Click the green "Commit changes..." button. As the banner on the top of the page says, this will write your changes to a new branch in your fork so you can open a pull request.
- Add a commit message or extended description beyond what's there if you want to provide more info and click the green Propose Changes button.
- This will automatically open a new page comparing the changes from your branch to the original repo. Click the green "Create pull request" button to create a PR with your edits to the sync.yml file to the OTTR repo.
- Edit the title or provide an extended description beyond what's there if you want (if you already did that when you created your commit, GitHub will copy that over). Click the green "Create pull request" button. This will create a PR in the OTTR repo.
- To make sure that we see the PR, you'll want to add a comment with `@cansavvy` to alert us there's a PR that needs to be merged. Scroll down to "Add a comment", type the `@cansavvy`, and click the green "Comment" button.
Some alternative information on these steps are available [here from GitHub](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) or from [James Priest's Gist on the Fork and PR Workflow](https://gist.github.com/james-priest/74188772ef2a6f8d7132d0b9dc065f9c) (note: you don't need to clone the forked repo locally, instead making edits online and committing to a new branch).
##### Links to open an Issue in an OTTR Template repository
| Repository | Issues Links |
|:---------------------:|:---------------------------------------------------------------------------|
| OTTR_Template | [Open a general issue here](https://github.com/jhudsl/OTTR_Template/issues/new/choose)<br/>[Open an issue to add a new repo to `sync.yml` for OTTR updates](https://github.com/jhudsl/OTTR_Template/issues/new?assignees=cansavvy&labels=&projects=&template=new-course-add-to-sync.md&title=)<br/>[Open an issue to update your repo name/location in `sync.yml` for OTTR updates](https://github.com/jhudsl/OTTR_Template/issues/new?assignees=cansavvy&labels=&projects=&template=update-course-info-for-sync.md&title=)|
| OTTR_Quizzes | [Open an issue here](https://github.com/jhudsl/OTTR_Quizzes/issues/new/choose) |
| OTTR_Template_Website | [Open an issue here](https://github.com/jhudsl/OTTR_Template_Website/issues/new/choose)|
#### Making edits to this file if you are part of the jhudsl GitHub organization
- 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`.
- 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](https://github.com/marketplace/actions/repo-file-sync-action#sync-the-same-files-to-multiple-repositories) to tailor which files you want updates for.
<p class="comment">
_If you have any questions about the implications of any of these updates or files, please tag `@cansavvy`._
</p>
<br>
### Create your website or course
Now you need to decide whether you want to build a course or a website and follow those instructions!
- [Make an OTTR Website](https://www.ottrproject.org/editing_website.html)
- [Make an OTTR Course](https://www.ottrproject.org/writing_content_courses.html)
If you wish to contribute to OTTR, please take a look at our [Code of Conduct](https://github.com/jhudsl/OTTR_Template/blob/main/code_of_conduct.md).