Merged upstream/main into olivroy-challenge-uncommited-tweaks

Author: olivroy

.covrignore

@@ -1,3 +1,3 @@
 R/deprec-*.R
 R/compat-*.R
-R/usethis-defunct.R
+R/usethis-deprecated.R

NAMESPACE

@@ -14,7 +14,6 @@ export(browse_github_issues)
 export(browse_github_pulls)
 export(browse_package)
 export(browse_project)
-export(browse_travis)
 export(create_download_url)
 export(create_from_github)
 export(create_github_token)
@@ -34,7 +33,6 @@ export(edit_rstudio_snippets)
 export(edit_template)
 export(gh_token_help)
 export(git_branch_default)
-export(git_credentials)
 export(git_default_branch)
 export(git_default_branch_configure)
 export(git_default_branch_rediscover)
@@ -87,8 +85,6 @@ export(use_agpl3_license)
 export(use_agpl_license)
 export(use_apache_license)
 export(use_apl2_license)
-export(use_appveyor)
-export(use_appveyor_badge)
 export(use_article)
 export(use_author)
 export(use_badge)
@@ -121,7 +117,6 @@ export(use_devtools)
 export(use_directory)
 export(use_git)
 export(use_git_config)
-export(use_git_credentials)
 export(use_git_hook)
 export(use_git_ignore)
 export(use_git_protocol)
@@ -159,7 +154,6 @@ export(use_partial_warnings)
 export(use_pipe)
 export(use_pkgdown)
 export(use_pkgdown_github_pages)
-export(use_pkgdown_travis)
 export(use_posit_cloud_badge)
 export(use_proprietary_license)
 export(use_r)
@@ -180,9 +174,9 @@ export(use_spell_check)
 export(use_standalone)
 export(use_template)
 export(use_test)
+export(use_test_helper)
 export(use_testthat)
 export(use_tibble)
-export(use_tidy_ci)
 export(use_tidy_coc)
 export(use_tidy_contributing)
 export(use_tidy_dependencies)
@@ -192,14 +186,11 @@ export(use_tidy_github)
 export(use_tidy_github_actions)
 export(use_tidy_github_labels)
 export(use_tidy_issue_template)
-export(use_tidy_labels)
 export(use_tidy_logo)
 export(use_tidy_style)
 export(use_tidy_support)
 export(use_tidy_thanks)
 export(use_tidy_upkeep_issue)
-export(use_travis)
-export(use_travis_badge)
 export(use_tutorial)
 export(use_upkeep_issue)
 export(use_usethis)

NEWS.md

@@ -1,8 +1,8 @@
 # usethis (development version)
 
-* `browse_github_token()`, `browse_github_pat()`, and `github_token()` have been removed after being deprecated in usethis 2.0.0. `create_github_token()`, `gh::gh_token()`, and `gh_token_help()` should be used instead.
+* `use_test_helper()` is a new function to create a test helper file (@olivroy, #1822).
 
-* `pr_pull_upstream()` and `pr_sync()` have been removed after being deprecated in usethis 2.0.0. `pr_merge_main()` and `pr_push()` should be used instead.
+* `use_cpp11()` makes it easier to update `NAMESPACE` (@pachadotdev, #1921).
 
 * `pr_merge_main()` now offers the choice to not open the files with merge conflicts (@olivroy, #1720).
 
@@ -44,6 +44,43 @@
 * `usethis::use_version()` now tolerates empty / blank lines preceding the
   first section title in the package NEWS file. (#1976)
 
+## 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:
+
+* Switch from git2r to gert (+ credentials).
+* Use of git config and the gh package to infer, e.g., the target repo spec.
+* Pivot towards GitHub Actions and away from Travis and AppVeyor.
+
+Functions that are removed and, where applicable, what to use instead:
+
+* `git_credentials()`
+* `use_git_credentials()`
+* `browse_github_token()` (do `create_github_token()`)
+* `browse_github_pat()` (do `create_github_token()`)
+* `github_token()` (do `gh_token_help()` or `gh::gh_token()`)
+* `pr_pull_upstream()` (do `pr_merge_main()`)
+* `pr_sync()` (do `pr_merge_main(); pr_push()`)
+* `use_appveyor()`
+* `use_appveyor_badge()`
+* `use_travis()`
+* `use_travis_badge()`
+* `browse_travis()`
+* `use_pkgdown_travis()`
+* `use_tidy_ci()` *deprecated in v2.1.0* (do `use_tidy_github_actions()`)
+* `use_tidy_labels()` *deprecated in v2.1.0* (do `use_tidy_github_labels()`)
+
+Function arguments that are removed:
+
+* `create_from_github(auth_token =, credentials =)`
+* `use_github(auth_token =, credentials =)`
+* `use_github_labels(repo_spec =, host =, auth_token =)`
+* `use_github_links(auth_token =, host =)`
+* `use_github_release(host =, auth_token =)`
+
 # usethis 2.2.3
 
 * Patch release with changes to `.Rd` files requested by CRAN.
@@ -206,14 +243,14 @@
 * `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
+## Deprecated functions
 
-* `use_tidy_eval()` is now defunct because it imports and re-exports a large
+* `use_tidy_eval()` is now deprecated 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
+  are now deprecated because we no longer recommend Travis or Appveyor. We
   recommend GitHub actions instead (#1517).
 
 # usethis 2.1.6
@@ -531,7 +568,7 @@ GitHub Actions is the preferred platform for continuous integration, because tha
 
 `use_tidy_pkgdown()` implements the complete pkgdown configuration used by the tidyverse team (#224).
 
-`pr_sync()` is defunct and can be replicated by calling `pr_pull()`, `pr_merge_main()`, then `pr_push()`.
+`pr_sync()` is deprecated and can be replicated by calling `pr_pull()`, `pr_merge_main()`, then `pr_push()`.
 
 ## Licensing improvements
 
@@ -1183,7 +1220,7 @@ build paths within it (#415, #425).
 
 * `create_from_github()`: the `repo` argument is renamed to `repo_spec`, since it takes input of the form "OWNER/REPO" (#376).
 
-* `use_depsy_badge()` is defunct. The Depsy project has officially concluded and is no longer being maintained (#354).
+* `use_depsy_badge()` is deprecated. The Depsy project has officially concluded and is no longer being maintained (#354).
 
 * `use_github()` fails earlier, with a more informative message, in the absence of a GitHub personal access token (PAT). Also looks for the PAT more proactively in the usual environment variables (i.e., GITHUB_PAT, GITHUB_TOKEN) (#320, #340, @cderv).
 

R/cpp11.R

@@ -12,6 +12,7 @@ use_cpp11 <- function() {
   check_is_package("use_cpp11()")
   check_installed("cpp11")
   check_uses_roxygen("use_cpp11()")
+  check_has_package_doc("use_cpp11()")
   use_src()
 
   use_dependency("cpp11", "LinkingTo")

R/create.R

@@ -188,15 +188,7 @@ create_from_github <- function(repo_spec,
                                rstudio = NULL,
                                open = rlang::is_interactive(),
                                protocol = git_protocol(),
-                               host = NULL,
-                               auth_token = deprecated(),
-                               credentials = deprecated()) {
-  if (lifecycle::is_present(auth_token)) {
-    deprecate_warn_auth_token("create_from_github")
-  }
-  if (lifecycle::is_present(credentials)) {
-    deprecate_warn_credentials("create_from_github")
-  }
+                               host = NULL) {
   check_protocol(protocol)
 
   parsed_repo_spec <- parse_repo_url(repo_spec)

R/github-labels.R

@@ -43,10 +43,6 @@
 #' This keeps the issue page visually harmonious while still giving enough
 #' variation to easily distinguish different types of label.
 #'
-#' @param repo_spec,host,auth_token `r lifecycle::badge("deprecated")`: These
-#'   arguments are now deprecated and will be removed in the future. Any input
-#'   provided via these arguments is not used. The target repo, host, and auth
-#'   token are all now determined from the current project's Git remotes.
 #' @param labels A character vector giving labels to add.
 #' @param rename A named vector with names giving old names and values giving
 #'   new names.
@@ -77,24 +73,11 @@
 #'   descriptions = c("foofiest" = "the foofiest issue you ever saw")
 #' )
 #' }
-use_github_labels <- function(repo_spec = deprecated(),
-                              labels = character(),
+use_github_labels <- function(labels = character(),
                               rename = character(),
                               colours = character(),
                               descriptions = character(),
-                              delete_default = FALSE,
-                              host = deprecated(),
-                              auth_token = deprecated()) {
-  if (lifecycle::is_present(repo_spec)) {
-    deprecate_warn_repo_spec("use_github_labels")
-  }
-  if (lifecycle::is_present(host)) {
-    deprecate_warn_host("use_github_labels")
-  }
-  if (lifecycle::is_present(auth_token)) {
-    deprecate_warn_auth_token("use_github_labels")
-  }
-
+                              delete_default = FALSE) {
   tr <- target_repo(github_get = TRUE, ok_configs = c("ours", "fork"))
   check_can_push(tr = tr, "to modify labels")
 

R/github.R

@@ -39,11 +39,6 @@
 #'   For a hypothetical GitHub Enterprise instance, either
 #'   "https://github.acme.com/api/v3" or "https://github.acme.com" is
 #'   acceptable.
-#' @param auth_token,credentials `r lifecycle::badge("deprecated")`: No longer
-#'   consulted now that usethis uses the gert package for Git operations,
-#'   instead of git2r; gert relies on the credentials package for auth. The API
-#'   requests are now authorized with the token associated with the `host`, as
-#'   retrieved by [gh::gh_token()].
 #'
 #' @export
 #' @examples
@@ -61,16 +56,7 @@ use_github <- function(organisation = NULL,
                        private = FALSE,
                        visibility = c("public", "private", "internal"),
                        protocol = git_protocol(),
-                       host = NULL,
-                       auth_token = deprecated(),
-                       credentials = deprecated()) {
-  if (lifecycle::is_present(auth_token)) {
-    deprecate_warn_auth_token("use_github")
-  }
-  if (lifecycle::is_present(credentials)) {
-    deprecate_warn_credentials("use_github")
-  }
-
+                       host = NULL) {
   visibility_specified <- !missing(visibility)
   visibility <- match.arg(visibility)
   check_protocol(protocol)
@@ -197,9 +183,6 @@ use_github <- function(organisation = NULL,
 #'   an interactive session, the user can confirm which repo to use for the
 #'   links. In a noninteractive session, links are formed using `upstream`.
 #'
-#' @param host,auth_token `r lifecycle::badge("deprecated")`: No longer consulted
-#'   now that usethis consults the current project's GitHub remotes to get the
-#'   `host` and then relies on gh to discover an appropriate token.
 #' @param overwrite By default, `use_github_links()` will not overwrite existing
 #'   fields. Set to `TRUE` to overwrite existing links.
 #' @export
@@ -208,16 +191,7 @@ use_github <- function(organisation = NULL,
 #' use_github_links()
 #' }
 #'
-use_github_links <- function(auth_token = deprecated(),
-                             host = deprecated(),
-                             overwrite = FALSE) {
-  if (lifecycle::is_present(auth_token)) {
-    deprecate_warn_auth_token("use_github_links")
-  }
-  if (lifecycle::is_present(host)) {
-    deprecate_warn_host("use_github_links")
-  }
-
+use_github_links <- function(overwrite = FALSE) {
   check_is_package("use_github_links()")
 
   gh_url <- github_url_from_git_remotes()

R/pr.R

@@ -967,22 +967,22 @@ pr_branch_delete <- function(pr) {
 
   if (is.null(pr_ref)) {
     ui_bullets(c(
-      "i" = "PR {.val {pr$pr_string}} originated from branch {.val {pr_remref}},
+      "i" = "PR {.href [{pr$pr_string}]({pr$pr_html_url})} originated from branch {.val {pr_remref}},
              which no longer exists."
     ))
     return(invisible(FALSE))
   }
 
   if (is.na(pr$pr_merged_at)) {
     ui_bullets(c(
-      "i" = "PR {.val {pr$pr_string}} is unmerged, we will not delete the
+      "i" = "PR {.href [{pr$pr_string}]({pr$pr_html_url})} is unmerged, we will not delete the
              remote branch {.val {pr_remref}}."
     ))
     return(invisible(FALSE))
   }
 
   ui_bullets(c(
-    "v" = "PR {.val {pr$pr_string}} has been merged, deleting remote branch
+    "v" = "PR {.href [{pr$pr_string}]({pr$pr_html_url})} has been merged, deleting remote branch
            {.val {pr_remref}}."
   ))
   # TODO: tryCatch here?

R/r.R

@@ -43,9 +43,12 @@
 #' @param name Either a string giving a file name (without directory) or
 #'   `NULL` to take the name from the currently open file in RStudio.
 #' @inheritParams edit_file
-#' @seealso The [testing](https://r-pkgs.org/testing-basics.html) and
+#' @seealso
+#' * The [testing](https://r-pkgs.org/testing-basics.html) and
 #'   [R code](https://r-pkgs.org/code.html) chapters of
 #'   [R Packages](https://r-pkgs.org).
+#' * [use_test_helper()] to create a testthat helper file.
+#'
 #' @export
 #'
 #' @examples
@@ -85,6 +88,55 @@ use_test <- function(name = NULL, open = rlang::is_interactive()) {
   invisible(TRUE)
 }
 
+#' Create or edit a test helper file
+#'
+#' This function creates (or opens) a test helper file, typically
+#' `tests/testthat/helper.R`. Test helper files are executed at the
+#' beginning of every automated test run and are also executed by
+#' [`load_all()`][pkgload::load_all]. A helper file is a great place to
+#' define test helper functions for use throughout your test suite, such as
+#' a custom expectation.
+#'
+#' @param name Can be used to specify the optional "SLUG" in
+#'   `tests/testthat/helper-SLUG.R`.
+#' @inheritParams edit_file
+#' @seealso
+#' * [use_test()] to create a test file.
+#' * The testthat vignette on special files
+#'   `vignette("special-files", package = "testthat")`.
+#' @export
+#'
+#' @examples
+#' \dontrun{
+#' use_test_helper()
+#' use_test_helper("mocks")
+#' }
+use_test_helper <- function(name = NULL, open = rlang::is_interactive()) {
+  maybe_name(name)
+
+  if (!uses_testthat()) {
+    ui_abort(c(
+      "x" = "Your package must use {.pkg testthat} to use a helper file.",
+      "_" = "Call {.run usethis::use_testthat()} to set up {.pkg testthat}."
+    ))
+  }
+
+  target_path <- proj_path(
+    path("tests", "testthat", as_test_helper_file(name))
+  )
+
+  if (!file_exists(target_path)) {
+    ui_bullets(c(
+      "i" = "Test helper files are executed at the start of all automated
+             test runs.",
+      "i" = "{.run devtools::load_all()} also sources test helper files."
+    ))
+  }
+  edit_file(target_path, open = open)
+
+  invisible(TRUE)
+}
+
 # helpers -----------------------------------------------------------------
 
 compute_name <- function(name = NULL, ext = "R", error_call = caller_env()) {
@@ -172,3 +224,14 @@ check_file_name <- function(name, call = caller_env()) {
 valid_file_name <- function(x) {
   grepl("^[a-zA-Z0-9._-]+$", x)
 }
+
+as_test_helper_file <- function(name = NULL) {
+  file <- name %||% "helper.R"
+  if (!grepl("^helper", file)) {
+    file <- glue("helper-{file}")
+  }
+  if (path_ext(file) == "") {
+    file <- path_ext_set(file, "R")
+  }
+  unclass(file)
+}