R Packages: Organize, Test, Document, and Share Your Code. 2 Ed

 Preface....5

Welcome!....5

Introduction....7

Philosophy....8

In This Book....9

What’s Not Here....11

Conventions Used in This Book....12

Colophon....13

O’Reilly Online Learning....15

How to Contact Us....15

Acknowledgments....16

I. Getting Started....24

1. The Whole Game....25

Load devtools and Friends....25

Toy Package: regexcite....26

Preview the Finished Product....27

create_package()....27

use_git()....30

Write the First Function....31

use_r()....33

load_all()....34

Commit strsplit1()....35

check()....36

Edit DESCRIPTION....37

use_mit_license()....38

document()....39

NAMESPACE Changes....41

check() Again....41

install()....41

use_testthat()....43

use_package()....45

use_github()....49

use_readme_rmd()....50

The End: check() and install()....53

Review....54

2. System Setup....59

devtools, usethis, and You....59

Personal Startup Configuration....60

R Build Toolchain....62

Windows....62

macOS....62

Linux....63

Verify System Prep....63

3. Package Structure and State....65

Package States....65

Source Package....66

Bundled Package....67

.Rbuildignore....70

Binary Package....72

Installed Package....74

In-Memory Package....78

Package Libraries....78

4. Fundamental Development Workflows....83

Create a Package....83

Survey the Existing Landscape....83

Name Your Package....84

Formal requirements....84

Things to consider....85

Use the available package....86

Package Creation....87

Where Should You create_package()?....88

RStudio Projects....89

Benefits of RStudio Projects....89

How to Get an RStudio Project....92

What Makes an RStudio Project?....92

How to Launch an RStudio Project....95

RStudio Project Versus Active usethis Project....96

Working Directory and Filepath Discipline....96

Test Drive with load_all()....98

Benefits of load_all()....98

Other Ways to Call load_all()....100

check() and R CMD check....100

Workflow....101

Background on R CMD check....103

5. The Package Within....105

Alfa: A Script That Works....105

Bravo: A Better Script That Works....107

Charlie: A Separate File for Helper Functions....109

Delta: A Failed Attempt at Making a Package....111

Echo: A Working Package....115

Foxtrot: Build Time Versus Run Time....118

Golf: Side Effects....120

Concluding Thoughts....124

Script Versus Package....124

Finding the Package Within....124

Package Code Is Different....125

II. Package Components....126

6. R Code....127

Organize Functions Into Files....127

Fast Feedback via load_all()....129

Code Style....130

Understand When Code Is Executed....131

Example: A Path Returned by system.file()....132

Example: Available Colors....133

Example: Aliasing a Function....135

Respect the R Landscape....136

Manage State with withr....138

Restore State with base::on.exit()....140

Isolate Side Effects....141

When You Do Need Side Effects....141

Constant Health Checks....143

7. Data....147

Exported Data....148

Preserve the Origin Story of Package Data....150

Documenting Datasets....152

Non-ASCII Characters in Data....153

Internal Data....154

Raw Data File....156

Filepaths....157

pkg_example() Path Helpers....159

Internal State....159

Persistent User Data....163

8. Other Components....166

Other Directories....166

Installed Files....168

Package Citation....169

Configuration Tools....170

III. Package Metadata....172

9. DESCRIPTION....173

The DESCRIPTION File....173

Title and Description: What Does Your Package Do?....175

Author: Who Are You?....177

URL and BugReports....180

The License Field....180

Imports, Suggests, and Friends....181

Minimum Versions....182

Depends and LinkingTo....183

An R Version Gotcha....185

Other Fields....186

Custom Fields....187

10. Dependencies: Mindset and Background....189

When Should You Take a Dependency?....190

Dependencies Are Not Equal....190

Prefer a Holistic, Balanced, and Quantitative Approach....193

Dependency Thoughts Specific to the tidyverse....195

Whether to Import or Suggest....196

Namespace....198

Motivation....198

The NAMESPACE File....200

Search Path....202

Function Lookup for User Code....202

Function Lookup Inside a Package....206

Attaching Versus Loading....209

Whether to Import or Depend....211

11. Dependencies: In Practice....214

Confusion About Imports....214

Conventions for This Chapter....215

NAMESPACE Workflow....215

Package Is Listed in Imports....217

In Code Below R/....217

How to not use a package in Imports....220

In Test Code....222

In Examples and Vignettes....222

Package Is Listed in Suggests....222

In Code Below R/....223

In Test Code....224

In Examples and Vignettes....225

Package Is Listed in Depends....226

In Code Below R/ and in Test Code....227

In Examples and Vignettes....227

Package Is a Nonstandard Dependency....228

Depending on the Development Version of a Package....228

Config/Needs/* Field....229

Exports....230

What to Export....231

Re-exporting....232

Imports and Exports Related to S3....233

12. Licensing....238

Big Picture....238

Code You Write....239

Key Files....240

More Licenses for Code....241

Licenses for Data....242

Relicensing....242

Code Given to You....243

Code You Bundle....244

License Compatibility....245

How to Include....246

Code You Use....246

IV. Testing....248

13. Testing Basics....249

Why Is Formal Testing Worth the Trouble?....249

Introducing testthat....251

Test Mechanics and Workflow....252

Initial Setup....252

Create a Test....253

Run Tests....255

Micro-Iteration....256

Mezzo-Iteration....256

Macro-Iteration....257

Test Organization....258

Expectations....260

Testing for Equality....261

Testing Errors....262

Snapshot Tests....264

Shortcuts for Other Common Patterns....269

14. Designing Your Test Suite....271

What to Test....271

Test Coverage....272

High-Level Principles for Testing....273

Self-Sufficient Tests....274

Self-Contained Tests....276

Plan for Test Failure....280

Repetition Is OK....282

Remove Tension Between Interactive and Automated Testing....284

Files Relevant to Testing....285

Hiding in Plain Sight: Files Below R/....286

tests/testthat.R....287

testthat Helper Files....287

testthat Setup Files....288

Files Ignored by testthat....290

Storing Test Data....290

Where to Write Files During Testing....291

15. Advanced Testing Techniques....293

Test Fixtures....293

Create useful_things with a Helper Function....294

Create (and Destroy) a Local useful_thing....295

Store a Concrete useful_thing Persistently....296

Building Your Own Testing Tools....297

Helper Defined Inside a Test....297

Custom Expectations....298

When Testing Gets Hard....300

Skipping a Test....300

testthat::skip()....300

Built-In skip() functions....302

Dangers of skipping....303

Mocking....303

Secrets....304

Special Considerations for CRAN Packages....304

Skip a Test....305

Speed....305

Reproducibility....306

Flaky Tests....306

Process and Filesystem Hygiene....307

V. Documentation....309

16. Function Documentation....310

roxygen2 Basics....311

The Documentation Workflow....311

roxygen2 Comments, Blocks, and Tags....316

Key Markdown Features....318

Title, Description, Details....319

Title....320

Description....321

Details....323

Arguments....324

Multiple Arguments....325

Inheriting Arguments....326

Return Value....328

Examples....330

Contents....331

Leave the World as You Found It....333

Errors....334

Dependencies and Conditional Execution....335

Intermixing Examples and Text....338

Reusing Documentation....338

Multiple Functions in One Topic....339

Inheriting Documentation....340

Child Documents....340

Help Topic for the Package....341

17. Vignettes....344

Workflow for Writing a Vignette....345

Metadata....347

Advice on Writing Vignettes....349

Diagrams....350

Links....350

Filepaths....351

How Many Vignettes?....353

Scientific Publication....353

Special Considerations for Vignette Code....354

Article Instead of Vignette....356

How Vignettes Are Built and Checked....357

R CMD build and Vignettes....357

R CMD check and Vignettes....360

18. Other Markdown Files....362

README....362

README.Rmd and README.md....363

NEWS....367

19. Website....370

Initiate a Site....370

Deployment....372

Now What?....375

Logo....375

Reference Index....377

Rendered Examples....377

Linking....377

Index Organization....378

Vignettes and Articles....379

Linking....380

Index Organization....381

NonVignette Articles....381

Development Mode....382

VI. Maintenance and Distribution....385

20. Software Development Practices....386

Git and GitHub....387

Standard Practice....388

Continuous Integration....389

GitHub Actions....390

R CMD check via GHA....390

Other Uses for GHA....392

21. Lifecycle....394

Package Evolution....395

Package Version Number....400

Tidyverse Package Version Conventions....401

Backward Compatibility and Breaking Change....403

Major Versus Minor Versus Patch Release....405

Package Version Mechanics....407

Pros and Cons of Breaking Change....407

Lifecycle Stages and Supporting Tools....409

Lifecycle Stages and Badges....409

Deprecating a Function....412

Deprecating an Argument....414

Deprecation Helpers....415

Dealing with Change in a Dependency....417

Superseding a Function....419

22. Releasing to CRAN....421

Decide the Release Type....423

Initial CRAN Release: Special Considerations....424

CRAN Policies....426

Keeping Up with Change....427

Double R CMD Checking....429

CRAN Check Flavors and Related Services....430

Reverse Dependency Checks....432

Revdeps and Breaking Changes....436

Update Comments for CRAN....438

The Submission Process....440

Failure Modes....442

Celebrating Success....443

Index....449

Turn your R code into packages that others can easily install and use. With this fully updated edition, developers and data scientists will learn how to bundle reusable R functions, sample data, and documentation together by applying the package development philosophy used by the team that maintains the "tidyverse" suite of packages. In the process, you'll learn how to automate common development tasks using a set of R packages, including devtools, usethis, testthat, and roxygen2.

Authors Hadley Wickham and Jennifer Bryan from Posit (formerly known as RStudio) help you create packages quickly, then teach you how to get better over time. You'll be able to focus on what you want your package to do as you progressively develop greater mastery of the structure of a package.

With this book, you will:

• Learn the key components of an R package, including code, documentation, and tests
• Streamline your development process with devtools and the RStudio IDE
• Get tips on effective habits such as organizing functions into files
• Get caught up on important new features in the devtools ecosystem
• Learn about the art and science of unit testing, using features in the third edition of testthat
• Turn your existing documentation into a beautiful and user friendly website with pkgdown
• Gain an appreciation of the benefits of modern code hosting platforms, such as GitHub