Table of Contents

Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Part I. Getting Started

1. The Whole Game. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Load devtools and Friends 1
Toy Package: regexcite 2
Preview the Finished Product 3
create_package() 3
use_git() 5
Write the First Function 6
use_r() 7
load_all() 7
Commit strsplit1() 9
check() 9
Edit DESCRIPTION 10
use_mit_license() 11
document() 12
NAMESPACE Changes 13
check() Again 14
install() 14
use_testthat() 15
use_package() 16
use_github() 19

iii
 use_readme_rmd() 20
The End: check() and install() 23
Review 24

2. System Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
devtools, usethis, and You 27
Personal Startup Configuration 28
R Build Toolchain 29
Windows 30
macOS 30
Linux 30
Verify System Prep 30

3. Package Structure and State. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Package States 33
Source Package 34
Bundled Package 35
.Rbuildignore 37
Binary Package 38
Installed Package 40
In-Memory Package 42
Package Libraries 43

4. Fundamental Development Workflows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Create a Package 47
Survey the Existing Landscape 47
Name Your Package 48
Package Creation 50
Where Should You create_package()? 51
RStudio Projects 52
Benefits of RStudio Projects 52
How to Get an RStudio Project 53
What Makes an RStudio Project? 54
How to Launch an RStudio Project 56
RStudio Project Versus Active usethis Project 56
Working Directory and Filepath Discipline 56
Test Drive with load_all() 58
Benefits of load_all() 58
Other Ways to Call load_all() 59

iv | Table of Contents
 check() and R CMD check 60
Workflow 61
Background on R CMD check 62

5. The Package Within. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Alfa: A Script That Works 63
Bravo: A Better Script That Works 65
Charlie: A Separate File for Helper Functions 67
Delta: A Failed Attempt at Making a Package 68
Echo: A Working Package 71
Foxtrot: Build Time Versus Run Time 74
Golf: Side Effects 76
Concluding Thoughts 78
Script Versus Package 78
Finding the Package Within 78
Package Code Is Different 79

Part II. Package Components

6. R Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Organize Functions Into Files 83
Fast Feedback via load_all() 85
Code Style 86
Understand When Code Is Executed 87
Example: A Path Returned by system.file() 88
Example: Available Colors 89
Example: Aliasing a Function 90
Respect the R Landscape 91
Manage State with withr 93
Restore State with base::on.exit() 94
Isolate Side Effects 95
When You Do Need Side Effects 95
Constant Health Checks 97

7. Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Exported Data 100
Preserve the Origin Story of Package Data 102
Documenting Datasets 104

Table of Contents | v
 Non-ASCII Characters in Data 104
Internal Data 105
Raw Data File 106
Filepaths 107
pkg_example() Path Helpers 109
Internal State 109
Persistent User Data 112

8. Other Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Other Directories 115
Installed Files 116
Package Citation 117
Configuration Tools 119

Part III. Package Metadata

9. DESCRIPTION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
The DESCRIPTION File 123
Title and Description: What Does Your Package Do? 125
Author: Who Are You? 126
URL and BugReports 128
The License Field 129
Imports, Suggests, and Friends 129
Minimum Versions 130
Depends and LinkingTo 131
An R Version Gotcha 132
Other Fields 133
Custom Fields 134

10. Dependencies: Mindset and Background. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

When Should You Take a Dependency? 136
Dependencies Are Not Equal 136
Prefer a Holistic, Balanced, and Quantitative Approach 138
Dependency Thoughts Specific to the tidyverse 140
Whether to Import or Suggest 141
Namespace 142
Motivation 143
The NAMESPACE File 144

vi | Table of Contents
 Search Path 146
Function Lookup for User Code 146
Function Lookup Inside a Package 148
Attaching Versus Loading 151
Whether to Import or Depend 152

11. Dependencies: In Practice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Confusion About Imports 155
Conventions for This Chapter 156
NAMESPACE Workflow 156
Package Is Listed in Imports 157
In Code Below R/ 158
In Test Code 161
In Examples and Vignettes 161
Package Is Listed in Suggests 161
In Code Below R/ 161
In Test Code 162
In Examples and Vignettes 163
Package Is Listed in Depends 164
In Code Below R/ and in Test Code 164
In Examples and Vignettes 165
Package Is a Nonstandard Dependency 165
Depending on the Development Version of a Package 165
Config/Needs/* Field 166
Exports 167
What to Export 167
Re-exporting 168
Imports and Exports Related to S3 169

12. Licensing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Big Picture 173
Code You Write 174
Key Files 175
More Licenses for Code 175
Licenses for Data 176
Relicensing 177
Code Given to You 177
Code You Bundle 178
License Compatibility 178

Table of Contents | vii

 How to Include 179
Code You Use 180

Part IV. Testing

13. Testing Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Why Is Formal Testing Worth the Trouble? 183
Introducing testthat 185
Test Mechanics and Workflow 186
Initial Setup 186
Create a Test 187
Run Tests 188
Test Organization 190
Expectations 192
Testing for Equality 193
Testing Errors 193
Snapshot Tests 195
Shortcuts for Other Common Patterns 199

14. Designing Your Test Suite. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

What to Test 201
Test Coverage 202
High-Level Principles for Testing 203
Self-Sufficient Tests 203
Self-Contained Tests 205
Plan for Test Failure 208
Repetition Is OK 210
Remove Tension Between Interactive and Automated Testing 211
Files Relevant to Testing 212
Hiding in Plain Sight: Files Below R/ 212
tests/testthat.R 213
testthat Helper Files 213
testthat Setup Files 214
Files Ignored by testthat 215
Storing Test Data 216
Where to Write Files During Testing 216

viii | Table of Contents

15. Advanced Testing Techniques. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Test Fixtures 219
Create useful_things with a Helper Function 220
Create (and Destroy) a Local useful_thing 220
Store a Concrete useful_thing Persistently 221
Building Your Own Testing Tools 222
Helper Defined Inside a Test 222
Custom Expectations 223
When Testing Gets Hard 224
Skipping a Test 224
Mocking 226
Secrets 227
Special Considerations for CRAN Packages 228
Skip a Test 228
Speed 228
Reproducibility 229
Flaky Tests 229
Process and Filesystem Hygiene 230

Part V. Documentation
16. Function Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
roxygen2 Basics 234
The Documentation Workflow 234
roxygen2 Comments, Blocks, and Tags 237
Key Markdown Features 239
Title, Description, Details 240
Title 240
Description 242
Details 243
Arguments 243
Multiple Arguments 244
Inheriting Arguments 245
Return Value 246
Examples 248
Contents 249
Leave the World as You Found It 250

Table of Contents | ix
 Errors 251
Dependencies and Conditional Execution 252
Intermixing Examples and Text 254
Reusing Documentation 254
Multiple Functions in One Topic 255
Inheriting Documentation 255
Child Documents 256
Help Topic for the Package 256

17. Vignettes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Workflow for Writing a Vignette 260
Metadata 261
Advice on Writing Vignettes 263
Diagrams 264
Links 264
Filepaths 265
How Many Vignettes? 266
Scientific Publication 266
Special Considerations for Vignette Code 267
Article Instead of Vignette 268
How Vignettes Are Built and Checked 269
R CMD build and Vignettes 269
R CMD check and Vignettes 271

18. Other Markdown Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

README 273
README.Rmd and README.md 274
NEWS 277

19. Website. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

Initiate a Site 281
Deployment 283
Now What? 284
Logo 285
Reference Index 286
Rendered Examples 286
Linking 286
Index Organization 287
Vignettes and Articles 288

x | Table of Contents
 Linking 288
Index Organization 289
NonVignette Articles 289
Development Mode 290

Part VI. Maintenance and Distribution

20. Software Development Practices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Git and GitHub 296
Standard Practice 296
Continuous Integration 298
GitHub Actions 298
R CMD check via GHA 298
Other Uses for GHA 299

21. Lifecycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Package Evolution 302
Package Version Number 304
Tidyverse Package Version Conventions 306
Backward Compatibility and Breaking Change 307
Major Versus Minor Versus Patch Release 309
Package Version Mechanics 310
Pros and Cons of Breaking Change 310
Lifecycle Stages and Supporting Tools 312
Lifecycle Stages and Badges 312
Deprecating a Function 314
Deprecating an Argument 315
Deprecation Helpers 316
Dealing with Change in a Dependency 317
Superseding a Function 318

22. Releasing to CRAN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Decide the Release Type 323
Initial CRAN Release: Special Considerations 323
CRAN Policies 325
Keeping Up with Change 326
Double R CMD Checking 327
CRAN Check Flavors and Related Services 329

Table of Contents | xi
 Reverse Dependency Checks 330
Revdeps and Breaking Changes 333
Update Comments for CRAN 334
The Submission Process 336
Failure Modes 337
Celebrating Success 338

Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

xii | Table of Contents