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