Contributing to tidywater • tidywater

Thank you for your interest in contributing to the tidywater package! This guide includes some best practices to help prepare your contribution. This guide is adapted from the tidyverse contribution guide. We will also generally adhere to the tidyverse code review principles.

First and foremost, we don’t wnat you to be intimidated by this process! If you don’t understand the steps in this guide, reach out to the maintainers on the issues page and we will help get you started. We believe all tidywater users can make valuable contributions, even those who are new to R and new to package development.

Fixing typos

You can fix typos, spelling mistakes, or grammatical errors in the documentation directly using the GitHub web interface, as long as the changes are made in the source file. This generally means you’ll need to edit roxygen2 comments in an .R, not a .Rd file. You can find the .R file that generates the .Rd by reading the comment in the first line of the .Rd file.

Bigger changes

If you want to make a bigger change, it’s a good idea to first file an issue and make sure someone from the team agrees that it’s needed. If you’ve found a bug, please file an issue that illustrates the bug with a minimal reprex (this will also help you write a unit test, if needed). See tidyverse guide on how to create a great issue for more advice.

Files and naming conventions
Pull request process
Code style

Files and naming conventions

R/ - R source code files.
- File name will typically match the name of the function (_chain and _once helper functions are in the same file as the baseline function. If you can’t find the file for the function you want to modify, try GitHub’s search function.
- Model functions follow the naming convention: “treatmentapplied_modelapplied”
tests/ - Test files.
- Each R/ file should have a corresponding test file. Create this file by opening the R/ file and running usethis::use_test() in your console.
- For help writing tests, look at the existing tests or read the documentation of the testthat package.
data-raw/compile_tidywater_data - R code used to generate data files for the package.
- If new data are added to the package, a corresponding usethis function must be run to generate the .rda file.
- For security and transparency reasons, data files that can not be re-created with scripts in the data-raw folder cannot be accepted in the package.
vignettes/ - Vignettes for the package
- All vignettes are generated with .Rmd files.
man/ - Roxygen documentation files automatically generated by devtools::document()

Pull request process

Fork the package and clone onto your computer. If you haven’t done this before, we recommend using usethis::create_from_github("BrownandCaldwell-Public/tidywater", fork = TRUE).
Install all development dependencies with pak::local_install_dev_deps(), and then make sure the package passes R CMD check by running devtools::check(). Also run devtools::document() to make sure you have everything needed to update documentation. If these don’t run cleanly or produce changes, it’s a good idea to ask for help before continuing.
Create a Git branch for your pull request (PR). We recommend using usethis::pr_init("brief-description-of-change").
Make your changes, commit to git, and then create a PR by running usethis::pr_push(), and following the prompts in your browser. The title of your PR should briefly describe the change. The body of your PR should contain Fixes #issue-number.
For user-facing changes, add a bullet to the top of NEWS.md (i.e. just below the first header). Follow the style described in https://style.tidyverse.org/news.html. At minimum include your GitHub user name and the issue numbers being resolved. For example:
- Add warning to chemdose_dbp when input water is outside model range (#12, @username)

Code style

New code should follow the tidyverse style guide. You can use the styler package to apply these styles, but please don’t restyle code that has nothing to do with your PR.
We use roxygen2, with Markdown syntax, for documentation.
We use testthat for unit tests. Contributions with test cases included are easier to accept.

Licensing

This package and any contributions you make will be licensed under MIT and Apache 2.0.
See GitHub’s terms of service to understand how your contribution will work with the existing licenses.

Code of Conduct

Please note that the tidywater project is released with a Contributor Code of Conduct. By contributing to this project you agree to abide by its terms.