Contributing to This Book

This chapter walks through the process of how to make changes and contribute to this book directly. While the focus is on writing your own markdown and contributing it via a pull request, please note that’s not the only way to contribute. If you have something to add but aren’t yet able to add a section directly, feel free to write your text in a Google Doc or similar and include it as a link in an issue on the book repo.

Prerequisites

To contribute to this guide directly, you need the following:

  1. A working knowledge of git and GitHub, in order to add your changes.
  2. A working knowledge of Markdown. Markdown is a pretty straightforward markup language, and the basics are pretty easy to learn – if you’ve ever sent texts in Slack or Discord, you’ve probably used some form of it before.

You’ll also need a program to edit the Markdown files in. While any text editor will work, the best options are probably one of the following:

You don’t really need to know anything about Quarto or any of the processes involved in building the book itself. However, if you want to get particularly fancy with a chapter, everything mentioned in the Quarto documentation should work automatically with this book.

Contribution Workflow

If you’re using RStudio, open the lab-manual project (either by double clicking the lab-manual.rproj file or by switching to it in the IDE).

You should always make sure you’re working with the most recent version of the book. Running the commands below in a terminal (such as the one in RStudio’s Terminal tab) will make sure you’re on the primary (main) branch of the book’s git repository, and that you’ve got the most up-to-date version:

git checkout main
git pull

We tend to use a branch-and-merge workflow with this project, meaning that most editing is done on a separate version of the book with the changes “merged” into the main book once they’re fully complete. To create a new branch, use the following command in a terminal, replacing your_branch_here with a name that describes your changes:

git checkout -b your_branch_here

Now that you’re on a new branch of the book, you can go ahead and edit to your heart’s content! Each chapter of the book is contained within a single .qmd file, which are organized into folders based on what section of the book they’re in. These .qmd files are Markdown documents which are converted into this website automatically; changes to these documents will automatically be reflected in the final rendered version.

If you’re adding a new chapter, you’ll also need to add it to the table of contents by adding it to the _quarto.yml file. Most of the time, you can copy and paste the entry for another chapter, change the file name to your new chapter’s file, and expect everything to work out. If you have any questions about how to get the structure you want, check out this section of the Quarto documentation.

To preview your changes in the rendered version, press the “Render Book” button in the “Build” tab in RStudio (or the equivalent button in VS Code). This will automatically render the website version of the book (as well as the PDF equivalent), which should then display either in your web browser or in a special pane of your editor. If it doesn’t, then open the index.html file in the _book folder on your computer to get the same preview.

Once you’re happy with your changes, you should push them up to GitHub. The following commands will push all of your changes up to a new branch on GitHub – don’t worry, this won’t mess up the live version of the book for everyone else:

git add .
git push -u

Once your changes are on GitHub, you’ll want to open a pull request. In the pull request, include any information about your changes that you think might be useful, and tag at least one person (by typing “@” and then their GitHub handle) to ask them to review your changes. If they don’t have any questions or concerns about your changes, they can merge your pull request, and your changes will now be live on the book for the whole lab to see!