We are pleased to announce that usethis 1.3.0 is now available on CRAN. usethis automates many common setup tasks for R projects, especially, but not only, for R packages. You can learn more about it at http://usethis.r-lib.org. Install it with:
usethis is part of the refactoring of the devtools package. We realize we need to say more about that process, so stay tuned for a dedicated post in the near future. Short version: devtools is here to stay, but it’s being separated into more manageable pieces under the hood.
Website, including setup advice
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
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.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 = "firstname.lastname@example.org") #> ✔ Writing to user git config file #> $user.name #>  "Jane Doe" #> #> $user.email #>  "email@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:
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)
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_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.
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.