R Packages: Organize, Test, Document, and Share Your Code

Copyright
Table of Contents
Preface
Welcome!
Introduction
Philosophy
In This Book
What’s Not Here
Conventions Used in This Book
Colophon
O’Reilly Online Learning
How to Contact Us
Acknowledgments
Part I. Getting Started
Chapter 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
Chapter 2. System Setup
devtools, usethis, and You
Personal Startup Configuration
R Build Toolchain
Windows
macOS
Linux
Verify System Prep
Chapter 3. Package Structure and State
Package States
Source Package
Bundled Package
.Rbuildignore
Binary Package
Installed Package
In-Memory Package
Package Libraries
Chapter 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 Versus 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
Chapter 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 Versus Run Time
Golf: Side Effects
Concluding Thoughts
Script Versus Package
Finding the Package Within
Package Code Is Different
Part II. Package Components
Chapter 6. R Code
Organize Functions Into Files
Fast Feedback via load_all()
Code Style
Understand When Code Is Executed
Example: A Path Returned by system.file()
Example: Available Colors
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
Chapter 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
Chapter 8. Other Components
Other Directories
Installed Files
Package Citation
Configuration Tools
Part III. Package Metadata
Chapter 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
Chapter 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
Chapter 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
Chapter 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
Part IV. Testing
Chapter 13. Testing Basics
Why Is Formal Testing Worth the Trouble?
Introducing testthat
Test Mechanics and Workflow
Initial Setup
Create a Test
Run Tests
Test Organization
Expectations
Testing for Equality
Testing Errors
Snapshot Tests
Shortcuts for Other Common Patterns
Chapter 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
Chapter 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 Filesystem Hygiene
Part V. Documentation
Chapter 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
Reusing Documentation
Multiple Functions in One Topic
Inheriting Documentation
Child Documents
Help Topic for the Package
Chapter 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
Chapter 18. Other Markdown Files
README
README.Rmd and README.md
NEWS
Chapter 19. Website
Initiate a Site
Deployment
Now What?
Logo
Reference Index
Rendered Examples
Linking
Index Organization
Vignettes and Articles
Linking
Index Organization
NonVignette Articles
Development Mode
Part VI. Maintenance and Distribution
Chapter 20. Software Development Practices
Git and GitHub
Standard Practice
Continuous Integration
GitHub Actions
R CMD check via GHA
Other Uses for GHA
Chapter 21. Lifecycle
Package Evolution
Package Version Number
Tidyverse Package Version Conventions
Backward Compatibility and Breaking Change
Major Versus Minor Versus 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
Chapter 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
Index
About the Authors
Colophon