Maintaining R packages

Why make a package?

To make it easier for others to re-use your code.
To signify that your code adheres to certain conventions agreed upon by the community.

What is an R package?

At minimum: a collection of R scripts in a directory called R/ + a DESCRIPTION file that describes which packages are needed to run your code.

If devtools::check() passes with no Errors, Warnings, or Notes, it's a valid R package!

Ideally you would also write unit tests in tests/, document your code inline with roxygen2, write tutorials in vignettes/, and share your code publicly with an open source license.

Tools to help

usethis
- create_package() - creates basic package structure to get you started. only need to run this once.
testthat
- test_file() - runs the tests that correspond to the R file you have open in RStudio.
devtools
- check() - runs all the unit tests, updates the documentation from roxygen comments, and checks lots of other things to make sure the R package is valid.
- build_site() - uses pkgdown to build the documentation website from the roxygen comments, vignettes, readme, etc.

Anatomy

.
├── DESCRIPTION
├── LICENSE
├── NAMESPACE
├── NEWS.md
├── R
│   ├── run_ml.R
│   └── utils.R
├── README.Rmd
├── README.md
├── data
│   ├── otu_mini_bin.rda
│   └── otu_small.rda
├── data-raw
│   ├── otu_large_bin.csv
│   └── otu_small.R
├── docs
├── man
├── tests
│   ├── testthat
│   │   ├── test-run_ml.R
│   │   └── test-utils.R
│   └── testthat.R
└── vignettes
    └── introduction.Rmd

Files edited by humans

DESCRIPTION
R/
tests/
vignettes/
data-raw/
README.Rmd
NEWS.md

Files edited by machines

NAMESPACE - devtools::document()
man/ - devtools::document()
README.md - Knit
data/ - all the scripts in data-raw/
docs/ - pkgdown::build_site()

Maintaining packages

Use Issues as a To-Do list

Issue titles should be short and informative.
Issue descriptions should contain more details about the problem or feature request.
Label issues with tags, e.g. bug, enhancement, documentation.
Assign issues to maintainers to track who will address what.
When addressing issues in commmits or PRs, reference the issue number with resolves #XX so it will be closed once the PR is merged into the main branch.

Development workflow

Pick an issue to address and assign yourself to it.
Create a new branch.
Edit the code.
Write new unit tests if needed.
Edit the code until your unit tests pass (testthat::test_file()).
Update the roxygen comments if needed. If it's a new function, in RStudio click Code > Use Roxygen Skeleton to create the scaffolding.
Make sure devtools::check() passes.
Commit your changes, tagging the relevant issue like resolves #XX.
Open a Pull Request and give it a short but descriptive title.

Reviewing pull requests

Read the description of the pull request & any relevant issues.
Read the new/edited code. You can ignore anything written by a machine.
If anything should be changed, write a detailed comment and link to the code section that needs modified.
Only approve the PR when it's ready to be merged into the main branch.

A non-exhaustive list of conditions that a PR must meet before it can be merged

The code works. There are adequate unit tests to make sure it works.
Functions are documented well with roxygen comments.
The code is readable. Refer to the tidyverse style guide for general guidelines.
The control flow is easy to follow.
devtools::check() passes with no Errors, Warnings, or Notes.
- We have GitHub Actions setup to run this automatically on PRs for mikropml and mothuR.

Resources

Relevant past code clubs

Testing R Code - with lots of exercises to practice.
Intro to Tidy Eval - i.e. how to use tidyverse functions in your own functions.
Documenting R Code
Exception Handling in R

kelly-sovacool/maintaining-R-pkgs.md