R Packages 2E: Organize, Test, Document, and Share Your Code (for True Epub)

Preface
Welcome!
Conventions Used in This Book
Using Code Examples
O’Reilly Online Learning
How to Contact Us
Acknowledgments
Conventions
Colophon
IntroductionTurn your R code into packages that others can easily download and use. This practical book shows you how to bundle reusable R functions, sample data, and documentation together by applying the package development philosophy used in the package known as the tidyverse (and beyond). In the process, you'll work with devtools, usethis, roxygen2, and testthat, a set of R packages that automate common development tasks.
Philosophy
In This Book
What’s Not Here
I. Getting Started
1. The Whole Game
Load devtools and Friends
Toy Package: regexcite
Preview the Finished Product
create_package()
use_git()
Write the First Function
use_r()
load_all()
Commit strsplit1()
check()
Edit DESCRIPTION
use_mit_license()
document()
NAMESPACE changes
check() Again
install()
use_testthat()
use_package()
use_github()
use_readme_rmd()
The End: check() and install()
Review
2. System Setup
Prepare Your System
devtools, usethis, and You
Personal Startup Configuration
R Build Toolchain
Windows
macOS
Linux
Verify System Prep
3. Package Structure and State
Package States
Source Package
Bundled Package
.Rbuildignore
Binary Package
Installed Package
In-Memory Package
Package Libraries
4. Fundamental Development Workflows
Create a Package
Survey the Existing Landscape
Name Your Package
Package Creation
Where Should You create_package()?
RStudio Projects
Benefits of RStudio Projects
How to Get an RStudio Project
What Makes an RStudio Project?
How to launch an RStudio Project
RStudio Project vs. Active usethis Project
Working Directory and Filepath Discipline
Test Drive with load_all()
Benefits of load_all()
Other Ways to Call load_all()
check() and R CMD check
Workflow
Background on R CMD check
5. The Package Within
Alfa: A Script That Works
Bravo: A Better Script That Works
Charlie: A Separate File for Helper Functions
Delta: A Failed Attempt at Making a Package
Echo: A Working Package
Foxtrot: Build Time vs. Run Time
Golf: Side Effects
Concluding Thoughts
Script vs. Package
Finding the Package Within
Package Code is Different
II. Package Components
6. R Code
Organise Functions Into Files
Fast Feedback via load_all()
Code Style
Understand When Code is Executed
Example: A Path Returned by system.file()
Example: Available Colours
Example: Aliasing a Function
Respect the R Landscape
Manage State with withr
Restore State with base::on.exit()
Isolate Side Effects
When You Do Need Side-Effects
Constant Health Checks
7. Data
Exported Data
Preserve the Origin Story of Package Data
Documenting Datasets
Non-ASCII Characters in Data
Internal Data
Raw Data File
Filepaths
pkg_example() Path Helpers
Internal State
Persistent User Data
8. Other Components
Other Directories
Installed Files
Package Citation
Configuration Tools
III. Package Metadata
9. DESCRIPTION
The DESCRIPTION File
Title and Description: What Does Your Package Do?
Author: Who Are You?
URL and BugReports
The License Field
Imports, Suggests, and Friends
Minimum Versions
Depends and LinkingTo
An R Version Gotcha
Other Fields
Custom Fields
10. Dependencies: Mindset and Background
When Should You Take a Dependency?
Dependencies Are Not Equal
Prefer a Holistic, Balanced, and Quantitative Approach
Dependency Thoughts Specific to the tidyverse
Whether to Import or Suggest
Namespace
Motivation
The NAMESPACE File
Search Path
Function Lookup for User Code
Function Lookup Inside a Package
Attaching Versus Loading
Whether to Import or Depend
11. Dependencies: In Practice
Confusion About Imports
Conventions for This Chapter
NAMESPACE Workflow
Package is Listed in Imports
In Code Below R/
In Test Code
In Examples and Vignettes
Package is Listed in Suggests
In Code Below R/
In Test Code
In Examples and Vignettes
Package is Listed in Depends
In Code Below R/ and in Test Code
In Examples and Vignettes
Package is a Nonstandard Dependency
Depending on the Development Version of a Package
Config/Needs/* Field
Exports
What to Export
Re-exporting
Imports and Exports Related to S3
12. Licensing
Big Picture
Code You Write
Key Files
More Licenses for Code
Licenses for Data
Relicensing
Code Given to You
Code You Bundle
License Compatibility
How to Include
Code You Use
IV. Testing
13. Testing Basics
Why is Formal Testing Worth the Trouble?
Introducing testthat
Test Mechanics and Workflow
Initial Setup
Create a Test
Run Tests
Test Organisation
Expectations
Testing for Equality
Testing Errors
Snapshot Tests
Shortcuts for Other Common Patterns
14. Designing Your Test Suite
What to Test
Test Coverage
High-Level Principles for Testing
Self-Sufficient Tests
Self-Contained Tests
Plan for Test Failure
Repetition is OK
Remove Tension Between Interactive and Automated Testing
Files Relevant to Testing
Hiding in Plain Sight: Files Below R/
tests/testthat.R
testthat Helper Files
testthat Setup Files
Files Ignored by testthat
Storing Test Data
Where to Write Files During Testing
15. Advanced Testing Techniques
Test Fixtures
Create useful_things with a Helper Function
Create (and Destroy) a local useful_thing
Store a Concrete useful_thing Persistently
Building Your Own Testing Tools
Helper Defined Inside a Test
Custom Expectations
When Testing Gets Hard
Skipping a Test
Mocking
Secrets
Special Considerations for CRAN Packages
Skip a Test
Speed
Reproducibility
Flaky Tests
Process and File System Hygiene
V. Documentation
16. Function Documentation
roxygen2 Basics
The Documentation Workflow
roxygen2 Comments, Blocks, and Tags
Key Markdown Features
Title, Description, Details
Title
Description
Details
Arguments
Multiple Arguments
Inheriting Arguments
Return Value
Examples
Contents
Leave the World as You Found It
Errors
Dependencies and Conditional Execution
Intermixing Examples and Text
Re-using Documentation
Multiple Functions in One Topic
Inheriting Documentation
Child Documents
Help Topic for the Package
17. Vignettes
Workflow for Writing a Vignette
Metadata
Advice on Writing Vignettes
Diagrams
Links
Filepaths
How Many Vignettes?
Scientific Publication
Special Considerations for Vignette Code
Article Instead of Vignette
How Vignettes Are Built and Checked
R CMD Build and Vignettes
R CMD Check and Vignettes
18. Other Markdown Files
README
README.Rmd and README.md
NEWS
19. Website
Initiate a Site
Deployment
Now What?
Logo
Reference Index
Rendered Examples
Linking
Index Organization
Vignettes and Articles
Linking
Index Organization
Non-Vignette Articles
Development Mode
VI. Maintenance and Distribution
20. Software Development Practices
Git and GitHub
Standard Practice
Continuous Integration
GitHub Actions
R CMD Check via GHA
Other Uses for GHA
21. Lifecycle
Package Evolution
Package Version Number
Tidyverse Package Version Conventions
Backward Compatibility and Breaking Change
Major vs Minor vs Patch Release
Package Version Mechanics
Pros and Cons of Breaking Change
Lifecycle Stages and Supporting Tools
Lifecycle Stages and Badges
Deprecating a Function
Deprecating an Argument
Deprecation Helpers
Dealing with Change in a Dependency
Superseding a Function
22. Releasing to CRAN
Decide the Release Type
Initial CRAN Release: Special Considerations
CRAN Policies
Keeping up with Change
Double R CMD Checking
CRAN Check Flavors and Related Services
Reverse Dependency Checks
Revdeps and Breaking Changes
Update Comments for CRAN
The Submission Process
Failure Modes
Celebrating Success
References