Usethis Versions Save

• Patch release with changes to .Rd files requested by CRAN.

• Implicit usage of numeric_version() via comparison now always provides character input. This is in response to a request from CRAN to anticipate future solutions to https://bugs.r-project.org/show_bug.cgi?id=18548.

• Internal helper cran_version(), used in functions such as use_release_checklist() and use_news_md(), is more resilient to situations where no CRAN mirror has been set (#1857).

• Internal usage of numeric_version() now always provides character input, rather than relying on implicit as.character() coercion. This is in response to a request from CRAN to anticipate future solutions to https://bugs.r-project.org/show_bug.cgi?id=18548 (#1869).

New functions

• use_author() is a new function to introduce a new person into the Authors@R field of DESCRIPTION (@avalcarcel9, #833).

• use_rstudio_preferences() lets you set RStudio preferences programmatically (#1518)

• use_standalone() is a new function that makes it easier to use standalone files provided by various low-level tidyverse packages, like rlang (#1654).

• use_upkeep_issue() is a new function to facilitate regular maintenance of your package. Similar to use_release_issue(), it opens an issue in your repo with a checklist of maintenance tasks. It will include additional bullets if your package includes an upkeep_bullets() function that returns a character vector (#1794).

Package development

• Although nested projects are discouraged, they can be useful in development contexts. create_package() now sets the correct package name and returns the correct package path for a package nested inside a project (#1647).

• use_article() no longer adds the rmarkdown package to Suggests. Instead, if rmarkdown is not already a dependency, it's added to Config/Needs/website. This means that a package that only uses articles (vs. vignettes) won't gain an unnecessary dependency on rmarkdown (#1700).

• use_data() now sets the appropriate minimal R version in DESCRIPTION, depending on which serialization format version you choose (@dpprdan, #1672).

• use_github_links() by default now appends the GitHub url to existing urls in in the URL field of DESCRIPTION, rather than replacing existing urls (#1805).

• use_latest_dependencies() no longer affects Suggests since those dependencies are not enforced (#1749).

• use_news_md() now places "(development version)" in the header of NEWS.md if there is a development version number in DESCRIPTION. It also sets the first bullet to "Initial CRAN submission" when it looks like a "new" package (#1708).

• use_coverage() no longer adds covr to Suggests, since the test-coverage GitHub Actions workflow takes care of installing covr (@Bisaloo, #1851).

Package release

• use_release_issue() will now remind you to run use_github_links() if necessary (@Bisaloo, #1754)

• use_release_issue() now encourages the creation of NEWS.md prior to submission, instead of after (#1755).

• use_github_release() now automatically pushes to GitHub (if safe) and automatically publishes the release, rather than requiring you to edit and publish the draft (#1385).

• use_github_release() no longer fails in the absence of NEWS.md (#1755).

• use_release_issue() will now remind you to check/close the milestone corresponding to the release, if it exists (#1642).

• use_version() and use_dev_version() gain a push argument to optionally push the result after committing. This is used to eliminate a manual step from the use_release_issue() checklist (#1385).

• use_revdep() no longer places an email template, because these days we are more likely to communicate with other maintainers about breaking changes via GitHub issues and pull requests (#1769).

Package file management

• rename_files() now also affects files in src/ (#1585).

• use_r() and use_test() now work with all active files in R/, src/, and tests/testthat/ (#1566).

• use_r() and use_test() now work with files containing . (#1690).

• use_rcpp(), use_c() and friends now work the same way as use_r() and use_test(): they'll take the default file name from the file you currently have open in RStudio (#1730).

Git and GitHub

• create_from_github() will now use an existing .Rproj file if it exists anywhere in the repo, not just the root directory. This is useful if you're working with repos that contain tools for multiple languages (#1680).

• git_sitrep() gains two arguments: tool and scope, which enables you to limit the report to, for example, tool = "git" or scope = "user". The default remains to provide a full report. Also, provides more feedback if git user's information is not set, and checks global git-email against user-level GitHub PAT (@ijlyttle, #1732, #1714, #1706).

• git_vaccinated() now treats a path configured as core.excludesFile like other user-supplied paths; in particular, any use of the ~/ home directory shortcut is expanded via fs::path_expand() (@dpprdan, #1560).

• use_github_action() now suggests possible actions when called without arguments (#1724).

• use_github_actions(), use_github_action_check_standard(), use_github_action_check_release(), and use_github_action_pr_commands() have been deprecated in favour of the new interactive powers of use_github_action() (#1724).

Minor improvements and fixes

• Links to the R Packages book have been updated to the second edition of the book (#1689).

• The SVG badges placed by use_lifecycle() have improved accessibility features, i.e. they advertise the lifecycle stage via the aria-label attribute (#1554, https://github.com/r-lib/lifecycle/issues/117).

• use_rscloud_badge() has been deprecated in favour of use_posit_cloud_badge(), and both functions now accept the updated url format of Posit Cloud projects (#1670).

• use_rstudio() gains a reformat argument which omits .Rproj settings that enforce file formatting conventions, e.g. around whitespace.
  create_from_github() uses this option when it introduces an .Rproj to a project that lacks one, making it easier to follow the project's existing conventions (#1679).

• write_over() and use_github_file() gain an overwrite argument (#1748).

Tidyverse-related

• use_release_issue() now uses internal release_extra_revdeps() to add extra revdep sources. Currently only use for internal Posit tooling, but we hope to extend to all users in the future (#1610).

• use_tidy_logo() is a new function that calls use_logo() on the appropriate hex sticker PNG file at https://github.com/rstudio/hex-stickers (#1871).

Defunct functions

• use_tidy_eval() is now defunct because it imports and re-exports a large number of functions that are no longer needed in order to do tidy evaluation (#1656).

• use_travis(), use_pkgdown_travis(), browse_travis(), and use_appveyor() are now defunct because we no longer recommend Travis or Appveyor. We recommend GitHub actions instead (#1517).

GitHub-related

use_github_action() and friends gain a ref argument, which defaults to the tag of the latest release in https://github.com/r-lib/actions (#1541).

use_github_actions_badge() now uses the same URLs as GitHub does via the "Create status badge" helper in the browser (#1525). This changes the significance of the name argument; now it really must be the name of the workflow configuration file.

All functions error more clearly when the requested operation is not supported for the "theirs" remote configuration (#1588).

Other changes

use_roxygen_md() gains an overwrite argument (#1599).

use_rscloud_badge() is a new function that creates a README badge indicating the repository can be launched in an RStudio Cloud project (@gvelasq, #1584).

use_data() gains an ascii argument, which is passed along to save() (@JosiahParry, #1625).

use_code_of_conduct() has been updated to version 2.1 of the Contributor Covenant (@batpigandme, #1591).

pkgdown-related functions no longer automatically strip a trailing slash from the pkgdown site URL, in order to play more nicely with CRAN's URL checks (#1526).

edit_pkgdown_config() is a new function that opens the pkgdown YAML configuration file for the current Project, if such a file exists.

The error thrown when reporting an unsupported GitHub configuration has been fixed for forward compatibility with a future version of rlang, i.e. what is anticipated to be rlang v1.0.0.

Version 2.1.4 was never released. Version was advanced from 2.1.4 to 2.1.5 strictly for CRAN (re-)submission purposes.

Modified a test to ensure that intermittent GitHub rate limiting does not lead to ungraceful failure on CRAN.

git_default_branch_rename() no longer errors on repos where README exists, but has no badge block.

git_default_branch_rediscover() prunes the defunct remote ref to the old default branch, e.g. origin/master.

Version 2.1.1 was never released. Version was advanced from 2.1.1 to 2.1.2 strictly for CRAN (re-)submission purposes.

Git default branch support

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

• git_branch_default() has been renamed to git_default_branch(), to place it logically in the new family of functions. The old name still works, but that won't be true forever.
• git_default_branch() is much more diligent about figuring out the default branch. Instead of only consulting the local repo, now we integrate local info with the default branch reported by the upstream or origin remote, if applicable.
  • This is intended to surface the case where a project has renamed its default branch and the local repo needs sync up with that.
• git_default_branch_rediscover() is a new function that helps contributors update their local repo (and personal fork, if applicable) when a project/repo renames its default branch.
• git_default_branch_rename() is a new function that helps a repo owner rename the default branch (both on GitHub and locally).
• git_default_branch_configure() is a new function to set the new Git configuration option init.defaultBranch, which controls the name of the initial branch of new local repos.
• git_sitrep() exposes init.defaultBranch and surfaces the more sophisticated analysis of git_default_branch().

Other GitHub-related changes

• git_sitrep() and gh_token_help() try even harder to help people get on the happy path with respect to their GitHub PAT (#1400, #1413, #1488, #1489, #1497).

• The minimum version of gh has been bumped to help / force more people to upgrade to the gh version that supports current GitHub PAT formats (@ijlyttle, #1454).

• use_github_file() is a new function related to use_template(). Instead of starting from a local file, use_github_file() grabs the contents of an arbitrary file on GitHub that the user has permission to read. It supports targeting a specific branch, tag, or commit and can follow a symlink (#1407). use_github_file() now powers use_github_action() and friends.

• use_github_release() is much more diligent about using any information left behind by devtools::submit_cran() or devtools::release(). Specifically, this applies to determining which SHA is to be tagged in the release. And this SHA, in turn, determines the consulted versions of DESCRIPTION (for package version) and NEWS.md (for release notes) (#1380).

• use_release_issue() also takes bullets from release_questions(), for compatibility with devtools::release().

• git_vaccinate(), edit_git_ignore(), and git_sitrep() are more careful to consult, reveal, and set the core.excludesFile setting in user's Git configuration (#1461).

• use_github_action_check_full() has been removed. It's overkill for the majority of R packages, which are better off with use_github_actions() or use_github_action_check_standard() (#1490).

• use_github_pages() and use_pkgdown_github_pages() use a new method for creating an empty, orphan gh-pages branch. This is necessary due to new GitHub behaviour, where it has become essentially impossible to refer to the empty tree (#1472).

• use_github() can create repositories with "internal" visibility, a feature that exists within GitHub Enterprise products (#1505).

Package development

• use_readme_[r]?md() no longer includes CRAN installation instructions in the initial template; instead, we only include GitHub-based install instructions or otherwise prompt the user to update instructions (#1507).

• use_import_from() is a new function that puts @importFrom pkg fun directives into a package in a consistent location (@malcolmbarrett, #1377).

• DESCRIPTION files generated by usethis no longer include LazyData by default, as per new CRAN checks; instead, LazyData is now added the first time you use use_data() (@malcolmbarrett, #1404).

• use_tidy_eval() has been updated to reflect current recommendations for using (and therefore exposing) tidy eval in other packages (@lionel-, #1445).

• use_pkgdown() automatically uses Bootstrap 5 if the pkgdown version supports it (anticipated for pkgdown 2.0.0).

• use_lifecycle() now imports lifecycle::deprecated() (#1419).

• use_code_of_conduct() now requires a contact argument to supply contact details for reporting CoC violations (#1269).

• use_package() no longer guides the user on how to use a dependency when no change was made (@malcolmbarrett, #1384).

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.

• use_tidy_dependencies() is a new function that sets up standard dependencies used by all tidyverse packages, except those that are designed to be dependency free (#1423).

• use_tidy_upkeep_issue() is a new function similar to use_release_issue() that creates a checklist-style issue to prompt various updates (#1416).

• use_tidy_release_test_env() has been deleted since we no longer recommend including test environments in cran-comments.md. There's no evidence that CRAN finds it useful, and it's annoying to keep up-to-date (#1365).

• use_tidy_github_labels() is the new name for use_tidy_labels() (#1430).

• use_tidy_github_actions() takes over for use_tidy_ci(), which is now deprecated.

User-level configuration

• "usethis.overwrite" is a new option. When set to TRUE, usethis overwrites an existing file without asking for user confirmation if the file is inside a Git repo. The normal Git workflow makes it easy to see and selectively accept/discard any proposed changes. This behaviour is strictly opt-in (#1424).

• Functions that provide code to load packages in your .Rprofile now use rlang::check_installed() to make sure the package is installed locally (@malcolmbarrett, #1398).

• edit_rstudio_prefs() and edit_rstudio_snippets() should work now on case-sensitive OSes, due to a path fix re: the location of RStudio's config files (@charliejhadley, #1420).

• All functions that require a package now ask you if you'd like to install it.

• Added edit_template() for opening and creating files in inst/templates (for use with use_template()) (@malcolmbarrett, #1319).

• use_article() now creates the file in the vignettes/articles/ (#548).

• use_lifecycle() has been updated for changes in our lifecycle workflow (#1323).

• use_tidy_pkgdown() has been renamed to use_pkgdown_github_pages() since the function is useful for anyone who wants to automatically publish to GitHub pages, not just the tidyverse team (#1308).

• use_release_issue() includes a bunch of minor improvements. Most importantly, for initial CRAN release we now include a number of common things that CRAN checks for that aren't in R CMD check.

• use_readme_rmd(), use_readme_md(), use_tidy_contributing(), and use_tidy_support() use updated logic for determining the OWNER/REPO spec of the target repo (#1312).