R Packages Organize, Test, Document, and Share Your Code (Hadley Wickham, Jenny Bryan) (Z-Library)

Hadley Wickham & Jennifer Bryan R Packages Organize, Test, Document, and Share Your Code Second Edition

DATA / DATA SCIENCE “A stellar reference book for package development beginners as well as more experienced folks who are curious about the fantastic devtools ecosystem.” —Maëlle Salmon “R Packages is an excellent and comprehensive guide to making your R code easier for others to reuse– or for future self!” —Sam Lau Author of Learning Data Science, assistant teaching professor in Data Science at UC San Diego R Packages Twitter: @oreillymedia linkedin.com/company/oreilly-media youtube.com/oreillymedia 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 Hadley Wickham is chief scientist at Posit, winner of the 2019 COPSS award, and a member of the R Foundation. Jennifer Bryan is a software engineer at Posit, a member of the R Foundation, and part of the tidyverse team that maintains more than 150 R packages. US $65.99 CAN $82.99 ISBN: 978-1-098-13494-5

Hadley Wickham and Jennifer Bryan R Packages Organize, Test, Document, and Share Your Code SECOND EDITION Boston Farnham Sebastopol TokyoBeijing

978-1-098-13494-5 [LSI] R Packages by Hadley Wickham and Jennifer Bryan Copyright © 2023 Hadley Wickham and Jennifer Bryan. All rights reserved. Printed in the United States of America. Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472. O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://oreilly.com). For more information, contact our corporate/institutional sales department: 800-998-9938 or corporate@oreilly.com. Acquisitions Editor: Aaron Black Development Editor: Sara Hunter Production Editor: Aleeya Rahman Copyeditor: Kim Cofer Proofreader: Piper Editorial Consulting, LLC Indexer: Potomac Indexing, LLC Interior Designer: David Futato Cover Designer: Karen Montgomery Illustrator: Kate Dullea June 2023: Second Edition Revision History for the Second Edition 2023-06-14: First Release See http://oreilly.com/catalog/errata.csp?isbn=9781098134945 for release details. The O’Reilly logo is a registered trademark of O’Reilly Media, Inc. R Packages, the cover image, and related trade dress are trademarks of O’Reilly Media, Inc. The views expressed in this work are those of the authors and do not represent the publisher’s views. While the publisher and the authors have used good faith efforts to ensure that the information and instructions contained in this work are accurate, the publisher and the authors disclaim all responsibility for errors or omissions, including without limitation responsibility for damages resulting from the use of or reliance on this work. Use of the information and instructions contained in this work is at your own risk. If any code samples or other technology this work contains or describes is subject to open source licenses or the intellectual property rights of others, it is your responsibility to ensure that your use thereof complies with such licenses and/or rights.

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 174 More Licenses for Code 175 Licenses for Data 176 Relicensing 176 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

Preface Welcome! Welcome to R Packages by Hadley Wickham and Jennifer Bryan. Packages are the fundamental units of reproducible R code. They include reusable R functions, the documentation that describes how to use them, and sample data. In this book you’ll learn how to turn your code into packages that others can easily download and use. Writing a package can seem overwhelming at first, so start with the basics and improve it over time. It doesn’t matter if your first version isn’t perfect as long as the next version is better. If you’re familiar with the first edition of the book, this preface describes the major changes so that you can focus your reading on the new areas. There are several main goals for this edition: • Update to reflect changes in the devtools package, specifically, its “conscious uncoupling” into a set of smaller, more focused packages. • Expand coverage of workflow and process, alongside the presentation of all the important moving parts that make up an R package. • Cover entirely new topics, such as package websites and GitHub Actions (GHA). All content has been completely revised and updated. Many chapters are new or reorganized and a couple have been removed: • New Chapter 1, “The Whole Game” previews the entire package development process. • New Chapter 2, “System Setup” has been carved out of the previous Introduction and gained more detail. xiii

1 Kirill Müller and Lorenz Walthert, “Styler: Non-Invasive Pretty Printing of R Code,” 2018. http://styler.r- lib.org. • The chapter formerly known as “Package Structure” has been expanded and split into two chapters, one covering package structure and state (Chapter 3) and another on workflows and tooling (Chapter 4). • New Chapter 5, “The Package Within” demonstrates how to extract reusable logic out of data analysis scripts and into a package. • The sections “Organizing Your Functions” and “Code Style,” from Chapter 6, “R Code” have been removed, in favor of an online style guide. The style guide is paired with the new styler package,1 which can automatically apply many of the rules. • The coverage of testing has expanded into three chapters: Chapter 13 for testing basics, Chapter 14 for test suite design, and Chapter 15 for various advanced topics. • Material around the NAMESPACE file and dependency relationships has been re-organized into two chapters: Chapter 10 provides technical context for think‐ ing about dependencies, and Chapter 11 gives practice instructions for using different types of dependencies in different settings. • New Chapter 12, “Licensing” expands earlier content on licensing into its own chapter. • The chapter on C/C++ has been removed. It didn’t have quite enough informa‐ tion to be useful, and since the first edition of the book, other materials have arisen that are better learning resources. • The chapter on Git/GitHub has been reframed around the more general topic of software development practices (Chapter 20). This no longer includes step-by- step instructions for basic tasks. The use of Git/GitHub has exploded since the first edition, accompanied by an explosion of learning resources, both general and specific to R (e.g., the website Happy Git and GitHub for the useR). Git/ GitHub still feature prominently throughout the book, most especially in Chapter 20. • The very short inst chapter has been combined into Chapter 8, with all the other directories that can be important in specific contexts, but that aren’t mission critical to all packages. xiv | Preface

Introduction In R, the fundamental unit of shareable code is the package. A package bundles together code, data, documentation, and tests and is easy to share with others. As of March 2023, there were over 19,000 packages available on the Comprehensive R Archive Network, or CRAN, the public clearinghouse for R packages. This huge variety of packages is one of the reasons that R is so successful: the chances are that someone has already solved a problem you’re working on, and you can benefit from their work by downloading their package. If you’re reading this book, you already know how to work with packages in the following ways: • You install them from CRAN with install.packages("x"). • You use them in R with library("x") or library(x). • You get help on them with package?x and help(package = "x"). The goal of this book is to teach you how to develop packages so that you can write your own, not just use other people’s. Why write a package? One compelling reason is that you have code that you want to share with others. Bundling your code into a package makes it easy for other people to use it, because like you, they already know how to use packages. If your code is in a package, any R user can easily download it, install it, and learn how to use it. But packages are useful even if you never share your code. As Hilary Parker says in her introduction to packages: “Seriously, it doesn’t have to be about sharing your code (although that is an added benefit!). It is about saving yourself time.” Organizing code in a package makes your life easier because packages come with conventions. For example, you put R code in R/, you put tests in tests/, and you put data in data/. These conventions are helpful because: • They save time—you don’t need to think about the best way to organize a project, you can just follow a template. • Standardized conventions lead to standardized tools—if you buy into R’s package conventions, you get many tools for free. Preface | xv

2 Ben Marwick, Carl Boettiger, and Lincoln Mullen, “Packaging Data Analytical Work Reproduci‐ bly Using r (and Friends),” The American Statistician 72, no. 1 (2018): 80–88, https://doi.org/ 10.1080/00031305.2017.1375986; Ben Marwick, Carl Boettiger, and Lincoln Mullen, “Packaging Data Ana‐ lytical Work Reproducibly Using r (and Friends)”, PeerJ Preprints 6 (2018):e3192v2, https://doi.org/10.7287/ peerj.preprints.3192v2. 3 Users of Emacs Speaks Statistics (ESS) will find that many of the workflows described in this book are also available there. For those loyal to vim, we recommend the Nvim-R plugin. It’s even possible to use packages to structure your data analyses (e.g., “Packaging Data Analytical Work Reproducibly Using r (and Friends)” in The American Statisti‐ cian or PeerJ Preprints),2 although we won’t delve deeply into that use case here. Philosophy This book espouses our philosophy of package development: anything that can be automated, should be automated. Do as little as possible by hand. Do as much as possible with functions. The goal is to spend your time thinking about what you want your package to do rather than thinking about the minutiae of package structure. This philosophy is realized primarily through the devtools package, which is the public face for a suite of R functions that automate common development tasks. The release of version 2.0.0 in October 2018 marked its internal restructuring into a set of more focused packages, with devtools becoming more of a metapackage. The usethis package is the subpackage you are most likely to interact with directly; we explain the devtools-usethis relationship in “devtools, usethis, and You” on page 27. As always, the goal of devtools is to make package development as painless as possible. It encapsulates the best practices developed by Hadley Wickham, initially from his years as a prolific solo developer. More recently, he has assembled a team of developers at Posit (formerly known as RStudio), who collectively look after hundreds of open source R packages, including those known as the tidyverse. The reach of this team allows us to explore the space of all possible mistakes at an extraordinary scale. Fortunately, it also affords us the opportunity to reflect on both the successes and failures, in the company of expert and sympathetic colleagues. We try to develop practices that make life more enjoyable for both the maintainer and users of a package. The devtools metapackage is where these lessons are made concrete. devtools works hand-in-hand with RStudio, which we believe is the best development environment for most R users. The most popular alternative to RStudio is currently Visual Studio Code (VS Code) with the R extension enabled. This can be a rewarding and powerful environment; however, it does require a bit more work to set up and customize.3 xvi | Preface

4 You might also enjoy the “quarto-ized” version at https://rstudio.github.io/r-manuals/r-exts/. RStudio Throughout the book, we highlight specific ways that RStudio can expedite your package development workflow, in specially format‐ ted sections like this. Together, devtools and RStudio insulate you from the low-level details of how pack‐ ages are built. As you start to develop more packages, we highly recommend that you learn more about those details. The best resource for the official details of package development is always the official Writing R Extensions manual.4 However, this manual can be hard to understand if you’re not already familiar with the basics of packages. It’s also exhaustive, covering every possible package component, rather than focusing on the most common and useful components, as this book does. Writing R Extensions is a useful resource once you’ve mastered the basics and want to learn what’s going on under the hood. In This Book The first part of the book is all about giving you the tools you need to start your package development journey, and we highly recommend that you read it in order. We begin in Chapter 1 with a run-through of the complete development of a small package. It’s meant to paint the big picture and suggest a workflow, before we descend into the detailed treatment of the key components of an R package. Then in Chapter 2 you’ll learn how to prepare your system for package development, and in Chapter 3 you’ll learn the basic structure of a package and how that varies across different states. Next, in Chapter 4, we’ll cover the core workflows that come up repeatedly for package developers. The first part of the book ends with another case study (Chapter 5), this time focusing on how you might convert a script to a package and discussing the challenges you’ll face along the way. The remainder of the book is designed to be read as needed. Pick and choose between the chapters as the various topics come up in your development process. First we cover key package components: Chapter 6 discusses where your code lives and how to organize it, Chapter 7 shows you how to include data in your package, and Chapter 8 covers a few less important files and directories that need to be discussed somewhere. Next we’ll dive into the package metadata, starting with DESCRIPTION in Chapter 9. We’ll then go deep into dependencies. In Chapter 10, we’ll cover the costs and bene‐ fits of taking on dependencies and provide some technical background on package namespaces and the search path. In Chapter 11, we focus on practical matters, such as Preface | xvii

how to use different types of dependencies in different parts of your package. This is also where we discuss exporting functions, which is what makes it possible for other packages and projects to depend on your package. We’ll finish off this part with a look at licensing in Chapter 12. To ensure your package works as designed (and continues to work as you make changes), it’s essential to test your code, so the next three chapters cover the art and science of testing. Chapter 13 gets you started with the basics of testing with the testthat package. Chapter 14 teaches you how to design and organize tests in the most effective way. Then we finish off our coverage of testing in Chapter 15, which teaches you advanced skills to tackle challenging situations. If you want other people (including future-you!) to understand how to use the functions in your package, you’ll need to document them. Chapter 16 gets you started using roxygen2 to document the functions in your package. Function documenta‐ tion is helpful only if you know what function to look up, so next in Chapter 17 we’ll discuss vignettes, which help you document the package as a whole. We’ll finish up documentation with a discussion of other important markdown files like README.md and NEWS.md in Chapter 18, and creating a package website with pkgdown in Chapter 19. The book concludes by zooming back out to consider development practices, such as the benefit of using version control and continuous integration (Chapter 20). We wrap things up by discussing the lifecycle (Chapter 21) of a package, including releasing it on CRAN (Chapter 22). This is a lot to learn, but don’t feel overwhelmed. Start with a minimal subset of useful features (e.g., just an R/ directory!) and build up over time. To paraphrase the Zen monk Shunryu Suzuki: “Each package is perfect the way it is—and it can use a little improvement.” What’s Not Here There are also specific practices that have little to no treatment here simply because we do not use them enough to have any special insight. Does this mean that we actively discourage those practices? Probably not, as we try to be explicit about practices we think you should avoid. So if something is not covered here, it just means that a couple hundred heavily used R packages are built without meaningful reliance on that technique. That observation should motivate you to evaluate how likely it is that your development requirements truly don’t overlap with ours. But sometimes the answer is a clear “yes,” in which case you’ll simply need to consult another resource. xviii | Preface