forked from hadley/r-pkgs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
preface.Rmd
134 lines (97 loc) · 7.97 KB
/
preface.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
# Preface {#sec-preface .unnumbered}
```{r, echo = FALSE}
source("common.R")
```
Welcome to the 2nd edition of R Packages!
If you're familiar with the 1st edition, 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"](https://www.tidyverse.org/articles/2018/10/devtools-2-0-0/#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.
All content has been completely revised and updated.
Many chapters are new or re-organized and a couple have been removed:
- New @sec-whole-game, "The Whole Game", previews the entire package development process.
- New @sec-setup, "System setup", has been carved out of the previous Introduction and gained more detail.
- The chapter formerly known as "Package structure" has been expanded and split into two chapters, one covering package structure and state (@sec-package-structure-state) and another on workflows and tooling (@sec-workflow101).
- New @sec-package-within, "The package within", demonstrates how to extract reusable logic out of data analysis scripts and into a package.
- The sections "Organising your functions" and "Code style", from @sec-r, "R code", have been removed, in favor of an online style guide, <https://style.tidyverse.org/>.
The style guide is paired with the new styler package [@styler] which can automatically apply many of the rules.
- The coverage of testing has expanded into three chapters: @sec-testing-basics for testing basics, @sec-testing-design for test suite design, and @sec-testing-advanced for various advanced topics.
- Material around the `NAMESPACE` file and dependency relationships has been re-organized into two chapters: @sec-dependencies-mindset-background provides technical context for thinking about dependencies and @sec-dependencies-in-practice gives practice instructions for using different types of dependencies in different settings.
- New @sec-license, "Licensing", expands earlier content on licensing into its own chapter.
- The chapter on C/C++ has been removed.
It didn't have quite enough information to be useful, and since the first edition of the book, other resources have arisen that are better learning resources.
- The "Other components" chapter has been removed.
- The chapter on Git/GitHub has been reframed around the more general topic of software development practices (@sec-sw-dev-practices).
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](https://happygitwithr.com/index.html)).
Git/GitHub still feature prominently throughout the book, most especially in @sec-sw-dev-practices.
- The very short `inst` chapter has been combined into @sec-misc, with all the other directories that can be important in specific contexts, but that aren't mission critical to all packages.
## Acknowledgments
```{r eval = FALSE, include = FALSE}
# code generates fodder for the prose below
library(desc)
get_contributors <- function(pkg = "devtools") {
desc_get_authors(system.file("DESCRIPTION", package = pkg))
}
# using packages represented by hex stickers in 2019 usethis useR! talk
# team agreed that was the "right" set of packages
get_contributors("devtools")
get_contributors("usethis")
get_contributors("roxygen2")
get_contributors("testthat")
get_contributors("desc")
get_contributors("pkgbuild")
get_contributors("pkgload")
get_contributors("rcmdcheck")
get_contributors("remotes")
get_contributors("revdepcheck")
get_contributors("sessioninfo")
```
Since the first edition of R Packages was published, the packages supporting the workflows described here have undergone extensive development.
The original trio of devtools, roxygen2, and testthat has expanded to include the packages created by the "conscious uncoupling" of devtools, as described in @sec-setup-usage.
Most of these packages originate with Hadley Wickham (HW), because of their devtools roots.
There are many other significant contributors, many of whom now serve as maintainers:
- devtools: HW, [Winston Chang](https://github.com/wch), [Jim Hester](https://github.com/jimhester) (maintainer, \>= v1.13.5), [Jennifer Bryan](https://github.com/jennybc) (maintainer \>= v2.4.3)
- usethis: HW, [Jennifer Bryan](https://github.com/jennybc) (maintainer \>= v1.5.0), Malcolm Barrett
- roxygen2: HW (maintainer), [Peter Danenburg](https://github.com/klutometis), [Manuel Eugster](https://github.com/mjaeugster)
- testthat: HW (maintainer)
- desc: [Gábor Csárdi](https://github.com/gaborcsardi) (maintainer), [Kirill Müller](https://github.com/krlmlr), [Jim Hester](https://github.com/jimhester)
- pkgbuild: HW, [Jim Hester](https://github.com/jimhester), [Gábor Csárdi](https://github.com/gaborcsardi) (maintainer \>= v1.2.1)
- pkgload: HW, [Jim Hester](https://github.com/jimhester), [Winston Chang](https://github.com/wch), [Lionel Henry](https://github.com/lionel-) (maintainer \>= v1.2.4)
- rcmdcheck: [Gábor Csárdi](https://github.com/gaborcsardi) (maintainer)
- remotes: HW, [Jim Hester](https://github.com/jimhester), [Gábor Csárdi](https://github.com/gaborcsardi) (maintainer), [Winston Chang](https://github.com/wch), [Martin Morgan](https://github.com/mtmorgan), [Dan Tenenbaum](https://github.com/dtenenba)
- revdepcheck: HW, [Gábor Csárdi](https://github.com/gaborcsardi) (maintainer)
- sessioninfo: HW, [Gábor Csárdi](https://github.com/gaborcsardi) (maintainer), [Winston Chang](https://github.com/wch), [Robert Flight](https://github.com/rmflight), [Kirill Müller](https://github.com/krlmlr), [Jim Hester](https://github.com/jimhester)
This book was [written and revised in the open](https://github.com/hadley/r-pkgs/) and it is truly a community effort: many people read drafts, fix typos, suggest improvements, and contribute content.
Without those contributors, the book wouldn't be nearly as good as it is, and we are deeply grateful for their help.
We are indebted to our colleagues at Posit, especially the tidyverse team, for being perpetually game to discuss package development practices.
The book has been greatly improved by the suggestions from our fantastic team of technical reviewers: Malcolm Barrett, Laura DeCicco, Zhian Kamvar, Tom Mock and Maëlle Salmon.
```{r, results = "asis", echo = FALSE, eval = TRUE}
library(tidyverse)
dat <- read_csv("data/contribs.csv", na = "NA", trim_ws = FALSE) |>
mutate(link = str_glue("[@{user}](https://github.com/{user}){maybe_name}"))
contrib_string <- dat |>
pull(link) |>
str_flatten_comma()
str_glue('
Thanks to all contributors the the first and second editions (in \\
alphabetical order by GitHub username):
{contrib_string}.')
```
## Conventions
Throughout this book, we write `fun()` to refer to functions, `var` to refer to variables and function arguments, and `path/` for paths.
Larger code blocks intermingle input and output.
Output is commented so that if you have an electronic version of the book, e.g., <https://r-pkgs.org>, you can easily copy and paste examples into R.
Output comments look like `#>` to distinguish them from regular comments.
## Colophon
This book was authored using [Quarto](https://quarto.org) inside [RStudio](https://www.rstudio.com/products/rstudio/).
The [website](https://r-pkgs.org) is hosted with [Netlify](https://www.netlify.com), and automatically updated after every commit by GitHub actions.
The complete source is available from [GitHub](https://github.com/hadley/r-pkgs).
This version of the book was built with:
```{r}
library(devtools)
library(roxygen2)
library(testthat)
devtools::session_info()
```