R Packages 2E: Organize, Test, Document, and Share Your Code (for True Epub)

Preface
    Welcome!
    Conventions Used in This Book
    Using Code Examples
    O’Reilly Online Learning
    How to Contact Us
    Acknowledgments
    Conventions
    Colophon
    IntroductionTurn your R code into packages that others can easily download and use. This practical book shows you how to bundle reusable R functions, sample data, and documentation together by applying the package development philosophy used in the package known as the tidyverse (and beyond). In the process, you'll work with devtools, usethis, roxygen2, and testthat, a set of R packages that automate common development tasks.
        Philosophy
        In This Book
        What’s Not Here
I. Getting Started
    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
    2. System Setup
        Prepare Your System
        devtools, usethis, and You
            Personal Startup Configuration
        R Build Toolchain
            Windows
            macOS
            Linux
        Verify System Prep
    3. Package Structure and State
        Package States
        Source Package
        Bundled Package
            .Rbuildignore
        Binary Package
        Installed Package
        In-Memory Package
        Package Libraries
    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 vs. 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
    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 vs. Run Time
        Golf: Side Effects
        Concluding Thoughts
            Script vs. Package
            Finding the Package Within
            Package Code is Different
II. Package Components
    6. R Code
        Organise Functions Into Files
        Fast Feedback via load_all()
        Code Style
        Understand When Code is Executed
            Example: A Path Returned by system.file()
            Example: Available Colours
            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
    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
    8. Other Components
        Other Directories
        Installed Files
            Package Citation
        Configuration Tools
III. Package Metadata
    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
    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
    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
    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
IV. Testing
    13. Testing Basics
        Why is Formal Testing Worth the Trouble?
        Introducing testthat
        Test Mechanics and Workflow
            Initial Setup
            Create a Test
            Run Tests
        Test Organisation
        Expectations
            Testing for Equality
            Testing Errors
            Snapshot Tests
            Shortcuts for Other Common Patterns
    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
    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 File System Hygiene
V. Documentation
    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
        Re-using Documentation
            Multiple Functions in One Topic
            Inheriting Documentation
            Child Documents
        Help Topic for the Package
    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
    18. Other Markdown Files
        README
            README.Rmd and README.md
        NEWS
    19. Website
        Initiate a Site
        Deployment
        Now What?
        Logo
        Reference Index
            Rendered Examples
            Linking
            Index Organization
        Vignettes and Articles
            Linking
            Index Organization
            Non-Vignette Articles
        Development Mode
VI. Maintenance and Distribution
    20. Software Development Practices
        Git and GitHub
            Standard Practice
        Continuous Integration
            GitHub Actions
            R CMD Check via GHA
            Other Uses for GHA
    21. Lifecycle
        Package Evolution
        Package Version Number
        Tidyverse Package Version Conventions
        Backward Compatibility and Breaking Change
        Major vs Minor vs 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
    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
    References