GitHub: Store the source files#

This topic isn’t intended to provide a complete guide to using GitHub. However, it does cover some basics and point out some information that may be unique to writing documentation or using Sphinx with GitHub. All documentation source files are stored in GitHub. For EMOD, there is a separate documentation repository; other projects store documentation source files under a /docs directory in the code repo.

The compiled HTML files that Sphinx produces used to be built using GitHub Actions or Bamboo and hosted on GitHub Pages. They are all now built and hosted on Read the Docs. See Read the Docs: Host the docs for more information.

Git terminology #

Git terminology can be a little confusing. Here are some important terms you should know when you get started.

Repository: A collection of all the files related to a project that is shared publicly or privately among a team.
Fork: A copy of a repository where you can work without affecting the shared repository until you are ready to share your changes with the rest of the team.
Branch: Technically, a movable pointer to a commit. Conceptually, a way to logically group your work. For example, you can have several branches, one for each project you are working on. Changes made in one branch won’t appear in another. This allows you to commit completed work in one branch, even if you have ongoing work in another.
Commit: A saved snapshot of your work in Git. A commit will only be stored locally until you push it to a remote repository.
Pull: Get a list of the commits on the remote repository and merge them in with your local changes.
Push: Add your local commits to the remote repository.
Pull request (PR): Submit the changes in your working branch for review to be merged into the main branch of the repository.

Documentation workflow #

Create tickets in GitHub to track all documentation work. Create tickets in the repo where the documentation source files are stored (usually the corresponding code repo). Tag these with a documentation label and all other relevant labels. Whenever possible, provide enough information in the tickets for content to be written by linking to relevant commits, specs, wiki pages, or naming the subject matter expert.
To begin working on the doc ticket, assign it to yourself.
Create a personal fork of the repositories to do your work in. Create a new working branch and make your changes. See Google style Python docstrings and Style guide for writing guidelines.
Always do a local doc build to verify your changes before submitting a pull request. See Sphinx: Build the HTML output for more information.
If you are making broad changes or setting up the documentation for the first time, create a “test” project in Read the Docs to verify that everything builds correctly there before you submit a PR. You can also temporarily share the RTD build output for reviewers. See Read the Docs: Host the docs for more information.
Submit a pull request to the default branch (most often this is main/master, but verify with the repository owner). See instructions below.

Quick fixes #

If you notice a small problem in the HTML documentation, such as a typo or incorrect formatting, you can also follow a simpler workflow to directly make the change. See Small changes to existing docs for more information.

Common GitHub tasks #

Create a personal fork #

Go to the repository: InstituteforDiseaseModeling/<repo>
Click Fork in the upper right.
Select your name.
On the forked repository (the URL will now include your GitHub username), click Clone or Download.
Copy the URL to the forked repository.
Open a command prompt and navigate to your GitHub folder.
Enter the following, pasting in the URL you copied earlier:
```
git clone https://github.com/<username>/<repo>.git
```

The repository may take a few minutes to download locally.

Set the origin and upstream remote sources #

By default, GitHub uses the concept of “origin” and “upstream” to refer to remote repositories. GitHub will set “origin” to your personal fork URL. You can pull from and push to your origin. We also recommend setting “upstream” to the shared repository so your forked repository can stay in sync with the changes made in the shared repo.

Open a command prompt and navigate to the GitHub Documentation folder.

Enter the following to view the current origin and upstream settings:

git remote -v

You should see the following output:

origin  https://github.com/<username>/<repo>.git(fetch)
origin  https://github.com/<username>/<repo>.git(push)

Type the following:

git remote add upstream https://github.com/InstituteforDiseaseModeling/<repo>.git

Enter the following to view the updated origin and upstream settings:

git remote -v

You should now see the following output:

origin  https://github.com/<username>/<repo>.git(fetch)
origin  https://github.com/<username>/<repo>.git(push)
upstream  https://github.com/InstituteforDiseaseModeling/<repo>.git(fetch)
upstream  https://github.com/InstituteforDiseaseModeling/<repo>.git(push)

Create and move between branches #

By default, GitHub creates a main/master branch and if you begin making commits immediately, those commits will be applied to that branch. However, it’s not recommended to make changes directly in main/master. Instead, create branches for different tasks. Then you can easily commit and push changes from one branch without worrying about in progress work you may have in other branches.

To list all local branches, enter the following:
```
git branch
```
To list all remote branches, enter:
```
git branch -r
```
To create a new branch, enter:
```
git checkout -b <branch_name>
```
It’s a good idea to give this an informative name. Note that the new branch will contain all changes present in the branch you have checked out when you create it. Therefore, if you want it to contain only changes in the main/master branch to start with, you should switch to main/master before creating the new branch.
To checkout an existing branch, enter:
```
git checkout <branch_name>
```

Commit your changes #

To see the list of updated files, enter:
```
git status
```
Add files to your commit list.
- To add them individually, enter:
```
git add <file_name>
```
- To add all updated files in a folder, enter:
```
git add .
```
To verify that all desired files are added, enter:
```
git status
```
To commit the files, enter:
```
git commit -m "<your commit message>"
```
If you begin your commit message with the GitHub issue number, GitHub will create a link between the issue and commit. For example:
```
git commit -m "#42 describes the answer to life, the universe, and everything"
```

Until you push your changes to a remote repository, these files will only be committed on your local branch.

Push your changes to your remote fork #

You can make one or more commits locally before pushing your changes remotely.

To push your changes to your remote fork, enter:
```
git push origin <branch name>
```

Warning

Do not push directly to upstream main/master. We use pull requests to review each other’s changes before merging them into the shared docs repo. This also enables us to test the Read the Docs build without changing the live hosted docs. See Read the Docs: Host the docs for more information.

Sync your fork with the main repo #

Your forked repository will not automatically stay in sync with the shared repository. Therefore, it’s a good practice to regularly get changes from the remote shared repository and merge them into your fork. The longer you go without syncing, the more likely you are to encounter merge conflicts.

To get changes from the main/master branch of the shared remote repository on your local branch:
```
git pull upstream main
```
The pull command can refer to any remote repository (in most cases, origin or upstream) and any branch on those repositories. Therefore, you can also pull changes from your personal remote fork into your local files. For example, if you pushed changes from one branch into your main/master branch and now want to merge those changes into a different branch with ongoing work, you can use git pull origin main.

Add your committed changes to the main repo using a pull request #

First, verify your changes by testing the Sphinx doc build locally. See Sphinx: Build the HTML output for more information.

In your browser, navigate to your forked repository.
Click New pull request.
Verify that the base fork refers to InstituteforDiseaseModeling/<repo> main/master or other default branch and that head fork refers to your personal fork and your working branch.
Verify that the comparison of changes looks correct.
Add an informative description of the changes made that includes a link to the corresponding GitHub issue (the pound sign followed by the issue number) and tag another member of the content team to review your pull request. Tag the subject matter expert or repo owner as needed.
Click Submit pull request. Once the reviewers have accepted the changes, the repo owner or primary reviewer will merge the PR.
Mark the GitHub issue as resolved using the labels.

Once your pull request has been merged, it’s a good idea to delete the branch you were working in. Once the PR is merged, Read the Docs should automatically trigger a build of the hosted documentation. See Read the Docs: Host the docs for more information.

Stash in-progress work #

If you have work in progress on a branch that you are not ready to commit, but need to switch to a different branch, you can “stash” those changes.

To set aside your uncommitted changes, enter:
```
git stash
```
Switch to another branch and make all changes you need there. When finished, switch back to the original branch.
To see your in-progress files again so you can pick up where you left off, enter:
```
git stash pop
```