usethis 3.0.0

Transition to cli package for UI

Deprecated function and argument removal

We are removing functions and arguments that were deprecated as of usethis v2.0.0, which was released in December 2020.

These changes have been in place for a long time now:

Functions that are removed and, where applicable, what to use instead:

Function arguments that are removed:

Other changes

usethis 2.2.3

usethis 2.2.2

usethis 2.2.1

usethis 2.2.0

New functions

Package development

Package release

Package file management

Git and GitHub

Minor improvements and fixes

Deprecated functions

usethis 2.1.6

Other changes

usethis 2.1.5

usethis 2.1.3

usethis 2.1.2

usethis 2.1.0

Git default branch support

usethis has a more sophisticated understanding of the default branch and gains several functions to support default branch renaming.

Package development

Aimed at the tidyverse team

These functions are exported for anyone to use, but are aimed primarily at the maintainers of tidyverse, r-lib, and tidymodels packages.

User-level configuration

usethis 2.0.1

usethis 2.0.0

Adoption of gert and changes to Git/GitHub credential handling

Usethis has various functions that help with Git-related tasks, which break down into two categories:

  1. Git tasks, such as clone, push, and pull. These are things you could do with command line Git.
  2. GitHub tasks, such as fork, release, and open an issue or pull request. These are things you could do in the browser or with the GitHub API.

We’ve switched from git2r to the gert package for Git operations (https://docs.ropensci.org/gert/). We continue to use the gh package for GitHub API work (https://gh.r-lib.org).

The big news in this area is that these lower-level dependencies are getting better at finding Git credentials, finding the same credentials as command line Git (and, therefore, the same as RStudio), and finding the same credentials as each other. This allows usethis to shed some of the workarounds we have needed in the past, to serve as a remedial “credential valet”.

Under the hood, both gert and gh are now consulting your local Git credential store, when they need credentials. At the time of writing, they are using two different even-lower-level packages to do this:

Even now, gert and gh should discover the same credentials, at least for github.com. In the future, these two packages may merge into one.

Git/GitHub credential management is covered in a new article: Managing Git(Hub) Credentials

The main user-facing changes in usethis are:

As a result, several functions are deprecated and several other functions have some deprecated arguments.

The switch to gert + credentials should eliminate most credential-finding fiascos. Gert also takes a different approach to wrapping libgit2, the underlying C library that does Git operations. The result is more consistent support for SSH and TLS, across all operating systems, without requiring special effort at install time. More users should enjoy Git remote operations that “just work”, for both SSH and HTTPS remotes. There should be fewer “unsupported protocol” errors.

GitHub remote configuration

Usethis gains a more formal framework for characterizing a GitHub remote configuration. We look at:

This is an internal matter, but users will notice that usethis is more clear about which configurations are supported by various functions and which are not. The most common configurations are reviewed in a section of Happy Git.

When working in a fork, there is sometimes a question whether to target the fork or its parent repository. For example, use_github_links() adds GitHub links to the URL and BugReports fields of DESCRIPTION. If someone calls use_github_links() when working in a fork, they probably want those links to refer to the parent or source repo, not to their fork, because the user is probably preparing a pull request. Usethis should now have better default behaviour in these situations and, in some cases, will present an interactive choice.

Default branch

There is increasing interest in making the name of a repo’s default branch configurable. Specifically, main is emerging as a popular alternative to master. Usethis now discovers the current repo’s default branch and uses that everywhere that, previously, we had hard-wired master.

git_branch_default() is a newly exported function that is also what’s used internally.

use_course(), use_zip(), and create_download_url() all have some support for forming the URL to download a .zip archive of a repo, based on a repo specification (e.g. OWNER/REPO) or a browser URL. These helpers now form a URL that targets HEAD of the repo, i.e. the default branch.

Changes to Git/GitHub functionality

The default Git protocol is now “https” and we no longer provide an interactive choice, by default, in interactive sessions. As always, a user can express a preference for “ssh” in individual function calls, for an R session via use_git_protocol(), and for all R sessions via the usethis.protocol option (#1262).

pr_resume() is a new function for resuming work on an existing local PR branch. It can be called argument-less, to select a branch interactively.

pr_fetch() can also be called with no arguments, to select a PR interactively. The owner argument is replaced by target, with a choice of the source (default) or primary repo.

pr_forget() is a new function for abandoning a PR you initiated locally or fetched from GitHub. It only does local clean up and, for example, doesn’t delete a remote branch or close a PR (#1263).

pr_view() can now be called with no arguments. If the current branch is associated with an open PR, we target that and, otherwise, we offer an interactive selection.

pr_finish() deletes the remote PR branch if the PR has been merged and the current user has the power to do so, i.e. an external contributor deleting their own branch or a maintainer deleting a branch associated with an internal PR (#1150). It no longer errors if the PR branch has already been deleted (#1196).

pr_pull_upstream() is renamed to pr_merge_main() to emphasize that it merges the main line of development into the current branch, where the main line of development is taken to mean the default branch, as reported by git_branch_default(), of the source repo, which could be either upstream or origin, depending on the situation.

create_from_github() will only create a read-only clone, due to lack of a GitHub personal access token, if explicitly directed to do so via fork = FALSE.

create_from_github() and use_tidy_thanks() accept browser and Git URLs as the repo_spec argument, to be friendlier to copy/paste. When a URL is passed, the host is also extracted from it.

create_github_token() is a new name for the function previously known as browse_github_token() and browse_github_pat().

issue_close_community() and issue_reprex_needed() are two new functions for maintainers who process lots of GitHub issues. They automate canned replies and actions, e.g. labelling or closing (#940).

GitHub Actions is the preferred platform for continuous integration, because that is what the tidyverse team currently uses and maintains. Functions related to Travis-CI and AppVeyor are soft-deprecated to raise awareness about this change and to make it clear that, if substantial maintenance becomes necessary, we may elect to retire the function (#1169).

browse_github_actions() is a new function to open the Actions page of the respective repo on GitHub, similar to existing browse_*() functions (@pat-s, #1102).

use_github_pages() is a new function to activate or reconfigure the GitHub Pages site associated with a repository (#224).

use_tidy_pkgdown() implements the complete pkgdown configuration used by the tidyverse team (#224).

pr_sync() is deprecated and can be replicated by calling pr_pull(), pr_merge_main(), then pr_push().

Licensing improvements

All use_*_license() functions now work for projects, not just packages.

use_apl2_license() (not use_apache_license()) and use_gpl3_license() no longer modify the license text (#1198).

use_mit_license() now sets the default copyright holder to “{package} authors”. This makes it more clear that the copyright holders are the contributors to the package; unless you are using a CLA there is no one copyright holder of a package (#1207).

New use_gpl_license() and use_agpl_license() make it easier to pick specific versions of the GPL and AGPL licenses, and to choose whether or not you include future versions of the license. Both default to version 3 (and above).

New use_proprietary_license() allows your package to pass R CMD check while making it clear that your code is not open source (#1163). Thanks to @atheriel for the blog post suggesting the wording: https://unconj.ca/blog/copyright-in-closed-source-r-packages-the-right-way.html

use_lgpl_license() now uses version 3 (and above), and gains new version and include_future argument to control which version is used.

use_gpl3_license(), use_agpl3_license() and use_apl2_license() have been deprecated in favour of the new version argument to use_gpl_license(), use_agpl_license() and use_apache_license().

The name argument to use_mit_license() has been changed to copyright_holder to make the purpose more clear. The name argument has been removed from all other license functions because it is not needed; no other license makes an assertion about who the copyright holder is.

RStudio preferences

usethis is now fully cognizant of the changes to RStudio preferences in RStudio 1.3:

edit_rstudio_snippets() looks in the new location, and if you have snippets in the old location, will automatically copy them to the new location (#1204)

New edit_rstudio_prefs() opens RStudio preferences file for editing (#1148).

use_blank_slate() can now configure your global, i.e. user-level, RStudio preference, in addition to project-level (#1018).

Other changes

browse_package() and browse_project() are new functions that let the user choose from a list of URLs derived from local Git remotes and DESCRIPTION (local or possibly on CRAN) (#1113).

The legacy "devtools.desc" option is no longer consulted when populating a new DESCRIPTION file. You must use the "usethis.description" now (#1069).

use_dev_package() gains a remote parameter to allow you to specify the remote. The existing behaviour, which adds an OWNER/REPO GitHub remote, remains the default (#918, @ijlyttle).

use_cpp11() is a new function to set up an R package to use cpp11.

create_package(roxygen = FALSE) once again writes a valid NAMESPACE file (and also has no Roxygen* fields in DESCRIPTION) (#1120).

create_package(), create_project(), create_from_github(), and proj_activate() work better with relative paths, inside and outside of RStudio (#1122, #954).

use_testthat() gains an edition argument to support testthat v3.0.0 (#1185)

use_version() now updates src/version.c if it exists and contains a line matching PKG_version = "x.y.z";.

usethis has been re-licensed as MIT (#1252, #1253).

Dependency changes

New Imports: gert, jsonlite (was already an indirect dependency), lifecycle, rappdirs

No longer in Imports: git2r, rematch2

usethis 1.6.3

Patch release to refactor usage of withr in the tests for forward compatibility with an upcoming withr release. All changes are within the usethis tests.

usethis 1.6.1

Patch release to align some path handling internals with an update coming in the fs package.

usethis 1.6.0

GitHub actions

Package creation

PR helpers

Other new features

Minor improvements and bug fixes

Dependency changes

New Imports: cli, rematch2, rlang.

gh minimum version is bumped to v.1.1.0, due to changed behaviour around requests that return nothing.

clisymbols is removed from Imports.

usethis 1.5.1

This is a patch release with various small features and bug fixes.

Using the pipe %>% or the tidy eval toolkit in your package

Git, GitHub, and pull requests

Build tools and continuous integration

Other

Dependency changes

R 3.1 is no longer explicitly supported or tested. Our general practice is to support the current release (3.6, at time of writing), devel, and the 4 previous versions of R (3.5, 3.4, 3.3, 3.2).

fs minimum version is stated to be v1.3.0.

glue minimum version is stated to be v1.3.0.

usethis 1.5.0

Git, GitHub (and GitLab)

usethis gains several functions to inspect and manipulate the Git situation for the current project = repository. We also provide more control and visibility into git2r’s workings, especially around credentials (usethis uses git2r for all Git operations).

Other improvements and bug fixes:

GitHub pull requests

We’ve added experimental functions to work with GitHub pull requests. They are aimed at both a maintainer (who may make, review, and modify pull requests) and a contributor (who may make or explore pull requests).

Partial file management

usethis gains tooling to manage part of a file. This is currently used for managing badges in your README and roxygen import tags:

Extending and wrapping usethis

Tidyverse standards

These standards are (aspirationally) used by all tidyverse packages; you are welcome to use them if you find them helpful.

New functions not already mentioned

Other minor bug fixes and improvements

Dependency changes

usethis 1.4.0

File system

All usethis file system operations now use the fs package (#177). This should not change how usethis functions, but users may notice these features of fs-mediated paths:

Extending or wrapping usethis

These changes make it easier for others to extend usethis, i.e. to create workflow packages specific to their organization, or to use usethis in other packages.

New functions

Other small changes and bug fixes

Dependency changes

New Imports: fs, glue, utils

No longer in Imports: backports, httr, rematch2, rmarkdown (moved to Suggests), styler (moved to Suggests)

usethis 1.3.0

New functions

usethis 1.2.0

New functions

Other changes

usethis 1.1.0

New helpers

Bug fixes and improvements

usethis 1.0.0

This is a new package that extracts out many functions that previously lived in devtools, as well as providing more building blocks so you can create your own helpers. As well as the many new helpers listed below, there are three main improvements to the package:

usethis is gradually evolving towards supporting more general R “projects”, not just packages. This is still a work in progress, so please let me know if you use a function that you think should work with projects but doesn’t. You can also try out the new create_project() which creates a basic RStudio project.

The concept of the working directory and the “base path” have been refined. Rather than using an argument to specify the active project, all use_ functions now use a global active project setting, as returned by proj_get(). This is cached throughout a session, although it will be updated by create_package() and create_project(). You’ll now get an clear error if you attempt to use_something() outside of a project, and create_something() will warn if you’re trying to create inside an existing project.

The output from all usethis commands has been reviewed to be informative but not overwhelming. usethis takes advantage of colour (using crayon and RStudio 1.1) to help chunk the output and clearly differentiate what you need to do vs. what has been done for you.

New functions

New edit functions

A new class of functions make it easy to edit common config files:

Updates

Building blocks

Bug fixes and minor improvements