usethis 1.3.0

Website, including setup advice

usethis now has a basic website, http://usethis.r-lib.org. It includes a setup article, with a “to do” list of tasks that are especially rewarding for R developers who use usethis and devtools.

In particular, usethis can help with the Git and GitHub side of your R projects, if you do the necessary software installation and configuration. usethis even offers several functions to help with this: configuration functions.

Secondary value of usethis

Working on this usethis release made me reflect on what it is good for. I think of it as a “jig”, in the woodworking sense (quoting Wikipedia:

[Jigs are made] to increase productivity through consistency, to do repetitive activities or to do a job more precisely.

An R package is set of files with a very specific structure and the definitive document is Writing R Extensions (WRE). A great many of these conventions are fairly simple and rote, yet don’t come up often enough for you to remember all the details. Examples include how to embed data in a package (see use_data()) or how to set up a vignette (see use_vignette()).

usethis provides a useful complement to WRE. Each function adds one specific piece of infrastructure to a package or project. Importantly, it documents this not (only) in prose, but also in executable R code. The implementation as discrete R functions allows us to make specific bits of documentation readily available, through the normal R help mechanism. If you use version control, the diff right after executing one of these functions also makes it clear what has been added or modified. Even if you don’t use the usethis functions all the time, they provide a handy reference and learning tool.

Git and GitHub

usethis has gained new functions to help with Git/GitHub and some existing functions are now more powerful.

use_git_config() allows you to set (or view) user.name and user.email from within R, at either the user or project level (global or local, in Git-speak).

use_git_config(user.name = "Jane Doe", user.email = "jane@example.com")
#> ✔ Writing to user git config file
#> $user.name
#> [1] "Jane Doe"
#> 
#> $user.email
#> [1] "jane@example.com"

browse_github_pat() takes you to a pre-filled web form to generate a GitHub personal access token (PAT). You are instructed how to store this as an environment variable, which usethis can then use downstream to, e.g., create new GitHub repositories on your behalf.

create_from_github() is not new, but is newly capable of both the “clone” or “fork and clone” workflows, with either the https or ssh protocols. It gains optional arguments for direct provision of the PAT, Git credentials, and GitHub host. usethis can now facilitate all the major workflows:

• GitHub first, local project/repo last: create_from_github() does this, with and without forking. In the case of a fork, both the origin and upstream remotes are configured, so you are ready to stay in sync with the upstream repo.
• Local project/repo first, GitHub last: use_github() does this.

Distribution of course materials

Many courses and workshops kick-off with the participants downloading a set of files from the instructor, such as slides or code examples. We have found this to be a reliable source of aggravation, due to the diversity of the learners’ file system knowledge and habits. You cannot assume that everyone will quickly download an entire set of files, and only those files, to a well-named folder, that they can find in their file browser. use_course() is a targeted solution to this problem, when time is of the essence.

use_course() accepts a link and interactively obtains user’s permission to download a ZIP archive and unpack it to a deliberately named folder on user’s desktop. If an RStudio Project file is found, the new Project is launched and, otherwise, the folder is opened in the file manager, e.g. Finder or File Explorer.

Here’s an example where the bit.ly shortlink points to the usethis source on GitHub.

usethis::use_course("bit.ly/usethis-shortlink-example")
#> ✔ Downloading ZIP file to '/Users/jenny/Desktop/r-lib-usethis-v1.2.0-93-g7d1c255.zip'
#> ✔ Unpacking ZIP file into '/Users/jenny/Desktop/r-lib-usethis-7d1c255/' (272 files extracted)

Community-specific conventions

The development conventions for tidyverse packages are gradually being codified into a set of use_tidy_*() helper functions. Some of these functions are directly useful to other developers, such as use_tidy_ci(), whereas others draw on templates very specific to the tidyverse organization, such as use_tidy_support().

• use_tidy_style() is a new function that uses the styler package to restyle code according to the tidyverse style guide. It’s an example of a function that is generally useful.
• use_tidy_github() is a new function that adds several standard files, such as contribution guidelines and an issue template, to make a project more transparent to outside contributors. These files include hyperlinks that are specific to the tidyverse, so other developers will need to edit the resulting files to reflect their project’s context.

The community has contributed new badging functions, such as use_bioc_badge() for the build status of BioConductor packages and use_binder_badge() for binder projects. The tidyverse team is starting to use use_lifecycle_badge() to indicate the developmental stage of a package.

Acknowledgements

A special salute to Maelle Salmon for encouraging the setup article, Ian Lyttle for regularly sharing his Windows pain, Carl Boettiger for exploring every possible GitHub scenario, Stefan Widgren for his stewardship of git2r, Jared Lander for commiseration re: workshops, and Jeroen Ooms for the clever pre-filled webform for GitHub PATs.

A big thanks goes out to the 53 users who contributed issues and pull requests since usethis became a separate package: @adomingues, @alexholcombe, @batpigandme, @benmarwick, @bhaskarvk, @cboettig, @colearendt, @CorradoLanera, @dchiu911, @dhimmel, @dougmet, @dpastoor, @eheinzen, @EmilHvitfeldt, @gaborcsardi, @gvegayon, @hadley, @ijlyttle, @jasonserviss, @jdblischak, @jennybc, @jeroen, @jimhester, @jjchern, @jonocarroll, @jrosen48, @jsta, @katrinleinweber, @kevinushey, @krlmlr, @lindbrook, @LiNk-NY, @lionel-, @llrs, @lorenzwalthert, @maelle, @malcolmbarrett, @martinjhnhadley, @maurolepore, @mixtrak, @muschellij2, @nbenn, @PeteHaitch, @r-pkgs-bot, @rdrivers, @richierocks, @s-fleck, @seankross, @tjmahr, @topepo, @uribo, @vnijs, and @webbedfeet.