contributing.qmd

---
number-sections: false
editor:
  markdown:
    canonical: true #FYI visual editor mangles shortcodes in links in older versions of RStudio https://github.com/quarto-dev/quarto/issues/337#issuecomment-1873437524
---

# Editing This Book {.unnumbered}

Prerequisites:

-   Create an account on [GitHub](https://github.com/) if you don't already have one.
-   Basic understanding of [markdown](https://quarto.org/docs/authoring/markdown-basics.html).
-   Optionally, knowledge of [Quarto](https://quarto.org/).

### Suggesting a change

To suggest a change, click the "Report an issue" link on any page or go to the [GitHub repository]({{< meta book.repo-url >}}) and open an issue.

### Small edits

To make an edit directly on GitHub, click the "{{< fa brands github >}} 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 GitHub repository it may prompt you to create a fork and submit changes as a pull request.
Your edits won't be "live" until someone (such as **PI_NAME**) merges these changes.
Don't worry if you don't know what "fork" and "pull request" mean yet—you should still be able to make edits this way!

### 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](https://quarto.org/docs/visual-editor/) for Quarto.

If you are an R user, there are some helpful functions in the [`usethis` package](https://usethis.r-lib.org/index.html) that can help with this workflow.

1.  Use `usethis::create_from_github("{{< meta book.repo-url >}}")` to fork and clone the repository.[^contributing-1]
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.  Run `usethis::pr_push()` to push your changes and open a pull request on GitHub.
8.  Once the pull request is merged on GitHub, run `usethis::pr_finish()` to clean things up.

::: callout-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 committing any changes to the `_freeze/` directory.
:::

[^contributing-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](https://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.