Merge branch 'main' into zero-coverage

Author: jennybc

DESCRIPTION

@@ -35,11 +35,8 @@ Imports:
     roxygen2 (>= 7.3.3),
     rversions (>= 2.1.2),
     sessioninfo (>= 1.2.3),
-    stats,
     testthat (>= 3.2.3),
-    tools,
     urlchecker (>= 1.0.1),
-    utils,
     withr (>= 3.0.2)
 Suggests:
     BiocManager (>= 1.30.18),
@@ -50,21 +47,17 @@ Suggests:
     DT (>= 0.23),
     foghorn (>= 1.4.2),
     gh (>= 1.3.0),
-    gmailr (>= 1.0.1),
     httr (>= 1.4.3),
     knitr (>= 1.39),
     lintr (>= 3.0.0),
-    MASS,
-    mockery (>= 0.4.3),
-    pingr (>= 2.0.1),
-    rhub (>= 1.1.1),
     rmarkdown (>= 2.14),
     rstudioapi (>= 0.13),
     spelling (>= 2.2)
 VignetteBuilder:
     knitr
 Config/Needs/website: tidyverse/tidytemplate
 Config/testthat/edition: 3
+Config/testthat/parallel: true
 Encoding: UTF-8
 Language: en-US
 Roxygen: list(markdown = TRUE)

NAMESPACE

@@ -13,6 +13,7 @@ export(build_vignettes)
 export(check)
 export(check_built)
 export(check_dep_version)
+export(check_doc_fields)
 export(check_mac_devel)
 export(check_mac_release)
 export(check_man)
@@ -82,8 +83,6 @@ export(uses_testthat)
 export(wd)
 export(with_debug)
 import(fs)
-importFrom(cli,cat_bullet)
-importFrom(cli,cat_rule)
 importFrom(ellipsis,check_dots_used)
 importFrom(lifecycle,deprecated)
 importFrom(memoise,memoise)
@@ -95,21 +94,6 @@ importFrom(pkgload,check_dep_version)
 importFrom(pkgload,is_loading)
 importFrom(pkgload,parse_deps)
 importFrom(pkgload,unload)
-importFrom(remotes,dev_package_deps)
-importFrom(remotes,github_pull)
-importFrom(remotes,github_release)
-importFrom(remotes,install_bioc)
-importFrom(remotes,install_bitbucket)
-importFrom(remotes,install_cran)
-importFrom(remotes,install_dev)
-importFrom(remotes,install_git)
-importFrom(remotes,install_github)
-importFrom(remotes,install_gitlab)
-importFrom(remotes,install_local)
-importFrom(remotes,install_svn)
-importFrom(remotes,install_url)
-importFrom(remotes,install_version)
-importFrom(remotes,update_packages)
 importFrom(sessioninfo,package_info)
 importFrom(sessioninfo,session_info)
 importFrom(stats,update)
@@ -120,11 +104,3 @@ importFrom(usethis,ui_path)
 importFrom(usethis,ui_todo)
 importFrom(usethis,ui_value)
 importFrom(usethis,use_test)
-importFrom(utils,available.packages)
-importFrom(utils,contrib.url)
-importFrom(utils,install.packages)
-importFrom(utils,installed.packages)
-importFrom(utils,modifyList)
-importFrom(utils,packageDescription)
-importFrom(utils,packageVersion)
-importFrom(utils,remove.packages)

NEWS.md

@@ -1,11 +1,19 @@
 # devtools (development version)
 
+* `bash()`, `create()`, `missing_s3()`, `reload()`, `show_news()`, and `wd()` are now deprecated. These functions are all historical parts of our workflow that we no longer use or recommend. `create()` is superseded by `usethis::create_package()`.
 * `build_manual()` reports more details on failure (#2586).
+* `check_doc_fields()` is a new function that checks for missing `\value` and `\examples` fields in Rd files, which are commonly flagged by CRAN (#2525).
+* `build_vignettes()` and `clean_vignettes()` are now deprecated. We no longer recommend building vignettes in this way; instead use `pkgdown::build_article()` to render articles locally (#2488).
+* `build_site()` now just calls `pkgdown::build_site()`, meaning that you will get more (informative) output by default (#2578).
 * New `check_mac_devel()` function to check a package using the macOS builder at https://mac.r-project.org/macbuilder/submit.html (@nfrerebeau, #2507)
+* `dev_sitrep()` now works correctly in Positron (#2618).
 * `is_loading()` is now re-exported from pkgload (#2556).
+* Package installation functions are now deprecated: `install_bioc()`, `install_bitbucket()`, `install_cran()`, `install_deps()`, `install_dev()`, `install_dev_deps()`, `install_git()`, `install_github()`, `install_gitlab()`, `install_local()`, `install_svn()`, `install_url()`, `install_version()`, `update_packages()`, `dev_package_deps()`, `github_pull()`, and `github_release()`. We now recommend pak (<https://pak.r-lib.org/>) for general package installation. See `?install-deprecated` for migration guidance.
 * `load_all()` now errors if called recursively, i.e. if you accidentally include a `load_all()` call in one of your R source files (#2617).
+* `release()` is deprecated in favour of `usethis::use_release_issue()`.
 * `show_news()` now looks for NEWS files in the same locations as `utils::news()`: `inst/NEWS.Rd`, `NEWS.md`, `NEWS`, and `inst/NEWS` (@arcresu, #2499).
 * `test_coverage()` and `test_coverage_active_file()` gain a new `report` argument that can be set to `"html"` (the default, for an interactive browser report), `"zero"` (prints uncovered lines to the console, used for LLMs and non-interactive contexts), or `"silent"` (#2632).
+* `test_file()` and `test_coverage_file()` are now defunct. These were deprecated in devtools 2.4.0 (2021-04-07) in favour of `test_active_file()` and `test_coverage_active_file()`. Removing `test_file()` eliminates the conflict with `testthat::test_file()`.
 
 # devtools 2.4.6
 

R/bash.R

@@ -1,8 +1,16 @@
-#' Open bash shell in package directory.
+#' Open bash shell in package directory
+#'
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' `bash()` is deprecated because we no longer use or recommend this workflow.
+#' Open bash shell in package directory
 #'
 #' @template devtools
 #' @export
+#' @keywords internal
 bash <- function(pkg = ".") {
+  lifecycle::deprecate_warn("2.5.0", "bash()")
   pkg <- as.package(pkg)
 
   withr::with_dir(pkg$path, system("bash"))

R/build-site.R

@@ -1,32 +1,14 @@
-#' Execute \pkg{pkgdown} build_site in a package
+#' Run `pkgdown::build_site()`
 #'
-#' `build_site()` is a shortcut for [pkgdown::build_site()], it generates the
-#'   static HTML documentation.
+#' This is a thin wrapper around [pkgdown::build_site()], used for generating
+#' static HTML documentation. Learn more at <https://pkgdown.r-lib.org>.
 #'
-#' @param path path to the package to build the static HTML.
-#' @param ...  additional arguments passed to [pkgdown::build_site()]
-#' @inheritParams install
-#'
-#' @return NULL
+#' @param path Path to the package to build the static HTML.
+#' @param ...  Additional arguments passed to [pkgdown::build_site()].
 #' @export
-build_site <- function(path = ".", quiet = TRUE, ...) {
+build_site <- function(path = ".", ...) {
   rlang::check_installed("pkgdown")
 
   save_all()
-
-  pkg <- as.package(path)
-
-  check_dots_used(action = getOption("devtools.ellipsis_action", rlang::warn))
-
-  withr::with_temp_libpaths(action = "prefix", code = {
-    install(pkg = pkg$path, upgrade = "never", reload = FALSE, quiet = quiet)
-    if (isTRUE(quiet)) {
-      withr::with_output_sink(
-        file_temp(),
-        pkgdown::build_site(pkg = pkg$path, ...)
-      )
-    } else {
-      pkgdown::build_site(pkg = pkg$path, ...)
-    }
-  })
+  pkgdown::build_site(pkg = path, ...)
 }

R/check-devtools.R

@@ -1,4 +1,4 @@
-#' Custom devtools release checks.
+#' Custom devtools release checks
 #'
 #' This function performs additional checks prior to release. It is called
 #' automatically by [release()].
@@ -8,15 +8,15 @@
 #' @export
 release_checks <- function(pkg = ".", built_path = NULL) {
   pkg <- as.package(pkg)
-  cat_rule(paste0("Running additional devtools checks for ", pkg$package))
+  cli::cat_rule(paste0("Running additional devtools checks for ", pkg$package))
 
   check_version(pkg)
   check_dev_versions(pkg)
   check_vignette_titles(pkg)
   check_news_md(pkg)
   check_remotes(pkg)
 
-  cat_rule()
+  cli::cat_rule()
 }
 
 check_dev_versions <- function(pkg = ".") {

R/check-doc.R

@@ -1,4 +1,4 @@
-#' Check documentation, as `R CMD check` does.
+#' Check documentation, as `R CMD check` does
 #'
 #' This function attempts to run the documentation related checks in the
 #' same way that `R CMD check` does. Unfortunately it can't run them
@@ -62,3 +62,54 @@ man_message <- function(x) {
     FALSE
   }
 }
+
+#' Check for missing documentation fields
+#'
+#' Checks all Rd files in `man/` and looks for any that have a `\usage` section
+#' (i.e. a function) but that *don't* have `\value` and `\examples` sections.
+#' These missing fields are flagged by CRAN on initial submission.
+#'
+#' @template devtools
+#' @param fields A character vector of Rd field names to check for.
+#' @returns A named list of character vectors, one for each field, containing
+#'   the names of Rd files missing that field. Returned invisibly.
+#' @export
+#' @examples
+#' \dontrun{
+#' check_doc_fields(".")
+#' }
+check_doc_fields <- function(pkg = ".", fields = c("value", "examples")) {
+  pkg <- as.package(pkg)
+  fields <- stats::setNames(fields, fields)
+
+  paths <- dir_ls(path(pkg$path, "man"), regexp = "\\.Rd$")
+  names(paths) <- path_rel(paths, pkg$path)
+  rd <- lapply(paths, tools::parse_Rd, permissive = TRUE)
+  rd_tags <- lapply(rd, \(x) unlist(lapply(x, attr, "Rd_tag")))
+
+  has_tag <- function(tags, this) {
+    any(paste0("\\", this) %in% tags)
+  }
+
+  has_usage <- vapply(rd_tags, has_tag, logical(1), this = "usage")
+  rd_tags <- rd_tags[has_usage]
+
+  results <- lapply(fields, function(field) {
+    missing <- !vapply(rd_tags, has_tag, logical(1), this = field)
+    names(rd_tags)[missing]
+  })
+
+  for (field in fields) {
+    missing <- results[[field]]
+    if (length(missing) > 0) {
+      cli::cli_inform(c(
+        "!" = "Missing {.code \\{field}} section in {length(missing)} file{?s}:",
+        stats::setNames(missing, rep("*", length(missing)))
+      ))
+    } else {
+      cli::cli_inform(c("v" = "All Rd files have a {.code \\{field}} section."))
+    }
+  }
+
+  invisible(results)
+}

R/check-git.R

@@ -1,4 +1,4 @@
-#' Git checks.
+#' Git checks
 #'
 #' This function performs Git checks checks prior to release. It is called
 #' automatically by [release()].
@@ -7,11 +7,11 @@
 #' @keywords internal
 git_checks <- function(pkg = ".") {
   pkg <- as.package(pkg)
-  cat_rule(paste0("Running Git checks for ", pkg$package))
+  cli::cat_rule(paste0("Running Git checks for ", pkg$package))
 
   git_report_branch(pkg)
   git_check_uncommitted(pkg)
-  cat_rule()
+  cli::cat_rule()
 }
 
 git_report_branch <- function(pkg) {

R/check-win.R

@@ -118,9 +118,7 @@ check_win <- function(
     ))
 
     email <- maintainer(pkg)$email
-    if (interactive() && yesno("Email results to {.strong {email}}?")) {
-      return(invisible())
-    }
+    confirm_maintainer_email(email)
   }
 
   built_path <- pkgbuild::build(
@@ -154,6 +152,24 @@ check_win <- function(
   invisible()
 }
 
+confirm_maintainer_email <- function(email, call = parent.frame()) {
+  if (!rlang::is_interactive()) {
+    return(FALSE)
+  }
+
+  if (!yesno("Email results to {.strong {email}}?")) {
+    return()
+  }
+
+  cli::cli_abort(
+    c(
+      "User declined upload.",
+      i = "Use `email = {.str your email}` to override."
+    ),
+    call = call
+  )
+}
+
 change_maintainer_email <- function(path, email, call = parent.frame()) {
   desc <- desc::desc(file = path)
 

R/check.R

@@ -85,7 +85,7 @@ check <- function(
   document <- document %||% can_document(pkg$roxygennote)
   if (document) {
     if (!quiet) {
-      cat_rule("Documenting", col = "cyan", line = 2)
+      cli::cat_rule("Documenting", col = "cyan", line = 2)
     }
     document(pkg, quiet = quiet)
     if (!quiet) {
@@ -94,7 +94,7 @@ check <- function(
   }
 
   if (!quiet) {
-    cat_rule("Building", col = "cyan", line = 2)
+    cli::cat_rule("Building", col = "cyan", line = 2)
     show_env_vars(pkgbuild::compiler_flags(FALSE))
   }
 
@@ -133,7 +133,7 @@ check <- function(
   )
 }
 
-can_document <- function(required, installed = packageVersion("roxygen2")) {
+can_document <- function(required, installed = utils::packageVersion("roxygen2")) {
   if (is.null(required)) {
     return(FALSE)
   }
@@ -222,7 +222,7 @@ check_built <- function(
 
   env_vars <- check_env_vars(cran, remote, incoming, force_suggests, env_vars)
   if (!quiet) {
-    cat_rule("Checking", col = "cyan", line = 2)
+    cli::cat_rule("Checking", col = "cyan", line = 2)
     show_env_vars(env_vars)
   }
 
@@ -271,7 +271,7 @@ aspell_env_var <- function() {
 
 show_env_vars <- function(env_vars) {
   cli::cat_line("Setting env vars:", col = "darkgrey")
-  cat_bullet(
+  cli::cat_bullet(
     paste0(format(names(env_vars)), ": ", unname(env_vars)),
     col = "darkgrey"
   )