Maintaining R packages - Schloss Lab Code Club 2021-04-19

maintaining-R-pkgs.md

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

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

Reviewing pull requests

1. Read the description of the pull request & any relevant issues.
2. Read the new/edited code. You can ignore anything written by a machine.
3. If anything should be changed, write a detailed comment and link to the code section that needs modified.
4. 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

• URSSI Winter School on Research Software Engineering
• Building Tidy Tools workshop at rstudio::conf
• R Packages book
• Advanced R book
• Tidyverse style guide
• Code Smells & Feels

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