Contributing to R4Epi
Over the years, we have learned so much from our students and colleagues, and we anticipate that there is much more we can learn from you – our readers. Therefore, we welcome and appreciate all constructive contributions to R4Epi!
The easiest way for you to contribute is to help us clean up the little typos and grammatical errors that inevitably sneak into the text.
If you spot a typo, you can offer a correction directly in GitHub. You will first need to create a free GitHub account: sign-up at github.com. Later in the book, there is an entire chapter on [using Git and Github]. Here, we’re just going to walk you through how to fix a typo without much explanation of how GitHub works.
Let’s say you spot a typo while reading along.
Next, click the edit button in the toolbar as shown in the screenshot below.
Close up, it looks like this:
The first time you click the icon, you will be taken to the R4Epi repository on GitHub and asked to Fork it. For our purposes, you can think of a GitHub repository as being similar to a shared folder on Dropbox or Google Drive.
“Forking the repository” basically just means “make a copy of the repository” on your GitHub account. In other words, copy all of the files that make up the R4Epi textbook to your GitHub account. Then, you can fix the typos you found in your copy of the files that make up the book instead of directly editing the actual files that make up the book. This is a safeguard to prevent people from accidentally making changes that shouldn’t be made.
🗒Side Note: Forking the R4Epi repository does not cost any money or add any files to your computer.
After you fork the repository, you will see a text editor on your screen.
The text editor will display the contents of the file (called an R markdown file), which is used to make the chapter you were looking at when you clicked the
edit button. In our example, it was the “Contributing to R4Epi” section of the file named
index.Rmd. We will learn more about R markdown files in the chapter on R markdown, but for now just know that R Markdown files contain a mix of R
code and plain text like the text you are reading right now. You may not understand the code yet, but you will probably be able to skim through the document and find the typo you want to fix.
Next, Scroll down through the text until you find the typo, and fix it.
Now, the only thing left to do is propose your typo fix to the authors. To do so, simply scroll to the bottom of the same screen where you made the edits to the file. There, you will see a “Propose changes” form box you can fill out. In the first line, type a brief (i.e., 72 characters or less) summary of the change you made. There is also a box to add a more detailed description of what you did, but you shouldn’t need to use it for a simple typo fix.
Next, click the “Propose changes” button. That will take you to another screen where you will be able to create a pull request. This screen is kind of busy, but try not to let it overwhelm you.
For now, we will focus on the three different sections of the screen that are highlighted with a red outline. We will start at the bottom and work our way up. The red box that is closest to the bottom of the screenshot shows us that the change we made was on line 93. We removed the word “typoo” (highlighted in red) and added the word “typo” (highlighted in green). The red box in the middle of the screenshot shows us the brief description we wrote for our proposed change – “Fixed a typo in index.Rmd.” Finally, the red box closest to the top of the screenshot is surrounding the “Create pull request” button. Let’s go ahead and click it now.
After doing so, we will get one final chance to amend our description of our proposed changes. We don’t want to change our description, so let’s go ahead and click “Create pull request” one more time. Our job is done! It is now up to the authors to review the changes we’ve proposed and “pull” them into the file in their repository.
In case you are curious, here is what the process looks like on the authors’ end. First, when we open the R4Epi repository page on GitHub, we will see that there is a new pull request.
When we open the pull request, we can see the proposed changes to the file.
Then, all we have to do is click the “Merge pull request button” and the fixed file is “pulled in” to replace the file with the typo.
There may be times when you see a problem that you don’t know how to fix, but you still want to make the authors aware of. In that case, you can create an issue in the R4Epi repository. To do so, navigate to the issue tracker using this link: https://github.com/brad-cannell/r4epi/issues.
Once there, you can check to see if someone has already raised the issue you are concerned about. If not, you can click the “New issue” button to raise it yourself.
Please note that R4Epi uses a Contributor Code of Conduct. By contributing to this book, you agree to abide by its terms.
This book was created by Brad Cannell and is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.