Editing This Book

Prerequisites:

• Create an account on GitHub if you don’t already have one.
• Basic understanding of markdown.
• Optionally, knowledge of Quarto.

Suggesting a change

To suggest a change, click the “Report an issue” link on any page or go to the GitHub repository and open an issue.

Small edits

To make an edit directly on GitHub, click the “ Edit this page” link on any page. This will open a page where you can make edits. When you are done, click the green “Commit changes…” button. If you do not have the ability to push directly to the repo it may prompt you to create a fork and submit changes as a pull request.

More substantial edits or new sections

To make more extensive edits or to add new sections, it’s probably best if you fork and clone the GitHub repository for this book and work on it on your computer using either RStudio or VSCode where you can take advantage of the visual markdown editor for Quarto.

If you are an R user, there are some helpful functions in the usethis package that can help with this workflow.

1. Use usethis::create_from_github("https://github.com/cct-datascience/group-procedures") to fork and clone the repository.¹
2. Use usethis::pr_init("name-of-my-branch") to create a new branch for your changes.
3. Edit existing .qmd, .md, or .Rmd files or create new ones.
4. If you’ve created a new file, be sure to add the path to it as a chapter in _quarto.yml.
5. Preview your changes by running quarto preview in the terminal.
6. Commit your changes with git.
7. Use usethis::pr_push() to push your changes and open a pull request.
8. Once the pull request is merged on GitHub, run usethis::pr_finish() to clean things up.

Warning

The GitHub action to deploy this book as a website does not have the ability to run any code! If you include any code chunks in your edits, you will need to render them locally before making your pull request by running quarto render in the terminal and commiting any changes to the _freeze/ directory.

---

1. If you haven’t set up git and GitHub on your computer, you’ll get an (hopefully informative) error. usethis::git_sitrep() can help you troubleshoot and we also recommend reading/searching happygitwithr.com. You only need to run this the first time you contribute to the book. For subsequent contributions, just open the RStudio project and start with step 2.