[skip vbump] Closes #534 #532 #529 Release 1.4...Release the 🦑 !!! (#535)

* docs: #532 short blurb on experimental fcns

* Move deprecated functions to Phase 3 and add Phase 1 deprecations (#536)

* Initial plan

* Move deprecated functions to Phase 3 and add Phase 1 deprecations

- Updated arg_name(), enumerate(), what_is_it(), and friendly_type_of() to Phase 3 (error) using deprecate_stop()
- Added Phase 1 deprecation messages to %or% and valid_time_units() using deprecate_inform()
- Updated documentation with lifecycle badges and deprecated keywords/families
- Updated unit tests to check for deprecation errors (Phase 3) and messages (Phase 1)
- Updated NEWS.md with deprecation phase changes

Co-authored-by: bms63 <10111024+bms63@users.noreply.github.com>

* tests: #529 new snaps who dis?

* docs: #529 regen docs; tests: reorg tests and snaps

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: bms63 <10111024+bms63@users.noreply.github.com>
Co-authored-by: Ben Straub <ben.x.straub@gsk.com>

* chore: #534 cleaning up spelling

* #534 fix lints and roxygen

* #534: update man

* #534: update NEWS

* chore: #534 aligning packages deps in admiraldev and admiral

* remove: #534 unused fcn

* docs: #486 remove CODEOWNERS

---------

Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: bms63 <10111024+bms63@users.noreply.github.com>
Co-authored-by: Edoardo Mancini <edoardo.mancini@roche.com>
Co-authored-by: Stefan Bundfuss <stefan.bundfuss@roche.com>

Author: 4 people

.github/CODEOWNERS

@@ -34,7 +34,7 @@ BugReports: https://github.com/pharmaverse/admiraldev/issues
 Depends:
     R (>= 4.1)
 Imports:
-    cli (>= 3.0.0),
+    cli (>= 3.6.2),
     dplyr (>= 1.1.1),
     glue (>= 1.6.0),
     lifecycle (>= 0.1.0),
@@ -44,7 +44,7 @@ Imports:
     roxygen2 (>= 7.0.0),
     stringr (>= 1.4.0),
     tidyr (>= 1.0.2),
-    tidyselect (>= 1.0.0),
+    tidyselect (>= 1.1.0),
     withr
 Suggests:
     diffdf,

DESCRIPTION

@@ -25,13 +25,25 @@ has been updated from 1.0.5 to 1.1.1. (#530)
 - The following function arguments are entering the next phase of the [deprecation process](https://pharmaverse.github.io/admiraldev/articles/programming_strategy.html#deprecation): (#2487) (#2595)
 
     **Phase 1 (message)**
+    
+    - `%or%` - Please get in touch if you are using this function!
+    - `valid_time_units()` - Please get in touch if you are using this function!
 
     **Phase 2 (warning)**
 
+    No functions or arguments in this Phase
+    
     **Phase 3 (error)**
 
+    - `arg_name()` - Use `rlang::caller_arg()` instead
+    - `enumerate()` - Use `cli` functionality instead, e.g., `cli::cli_abort('{.val {letters[1:3]}}')`
+    - `what_is_it()` - Use `cli` functionality instead, e.g., `cli::cli_abort('{.obj_type_friendly {letters}}')`
+    - `friendly_type_of()` - Use `cli` functionality instead, e.g., `cli::cli_abort('{.obj_type_friendly {letters}}')`
+    
     **Phase 4 (removed)**
 
+    No functions or arguments in this Phase
+
 ## Documentation
 
 - Added the "Ask AI" widget to the the bottom right of each page. It enables users to ask questions about `{admiraldev}` and the
@@ -48,6 +60,8 @@ and to improve its formatting. (#365)
 full title of all linked resources to ensure that resources can be found if links
 become defunct or broken. (#463)
 
+- Removed use of CODEOWNERS and discussion in Pull Request Guidance (#486)
+
 ## Various
 
 - Added various unit tests to improve the test coverage of `{admiraldev}`. (#524)

NEWS.md

@@ -1,5 +1,10 @@
 #' Return English-friendly messaging for object-types
 #'
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' This function is *deprecated*, please use `cli` functionality instead.
+#'
 #' @param x Any R object.
 #' @param value Whether to describe the value of `x`.
 #' @param length Whether to mention the length of vectors and lists.
@@ -14,174 +19,13 @@
 #' @return A string describing the type. Starts with an indefinite
 #'   article, e.g. "an integer vector".
 #'
-#' @keywords dev_utility
-#' @family dev_utility
+#' @keywords deprecated
+#' @family deprecated
 friendly_type_of <- function(x, value = TRUE, length = FALSE) { # nolint
-  lifecycle::deprecate_soft(
+  lifecycle::deprecate_stop(
     when = "1.1.0",
     what = "admiraldev::friendly_type_of()",
     details = "This function was primarily used in error messaging, and can be replaced
                with 'cli' functionality: `cli::cli_abort('{.obj_type_friendly {letters}}')`."
   )
-
-  if (rlang::is_missing(x)) {
-    return("absent")
-  }
-
-  if (is.object(x)) {
-    if (inherits(x, "quosure")) {
-      type <- "quosure"
-    } else {
-      type <- paste(class(x), collapse = "/")
-    }
-    return(sprintf("a <%s> object", type))
-  }
-
-  if (!rlang::is_vector(x)) {
-    return(.rlang_as_friendly_type(typeof(x)))
-  }
-
-  n_dim <- length(dim(x))
-
-  if (value && !n_dim) {
-    if (rlang::is_na(x)) {
-      return(switch(typeof(x),
-        logical = "`NA`",
-        integer = "an integer `NA`",
-        double = "a numeric `NA`",
-        complex = "a complex `NA`",
-        character = "a character `NA`",
-        .rlang_stop_unexpected_typeof(x)
-      ))
-    }
-    if (length(x) == 1 && !rlang::is_list(x)) {
-      return(switch(typeof(x),
-        logical = if (x) "`TRUE`" else "`FALSE`",
-        integer = "an integer",
-        double = "a number",
-        complex = "a complex number",
-        character = if (nzchar(x)) "a string" else "`\"\"`",
-        raw = "a raw value",
-        .rlang_stop_unexpected_typeof(x)
-      ))
-    }
-    if (length(x) == 0) {
-      return(switch(typeof(x),
-        logical = "an empty logical vector",
-        integer = "an empty integer vector",
-        double = "an empty numeric vector",
-        complex = "an empty complex vector",
-        character = "an empty character vector",
-        raw = "an empty raw vector",
-        list = "an empty list",
-        .rlang_stop_unexpected_typeof(x)
-      ))
-    }
-  }
-
-  type <- .rlang_as_friendly_vector_type(typeof(x), n_dim)
-
-  if (length && !n_dim) {
-    type <- paste0(type, sprintf(" of length %s", length(x)))
-  }
-
-  type
-}
-
-# Used in building `friendly_type_of()` above
-.rlang_as_friendly_vector_type <- function(type, n_dim) {
-  if (type == "list") {
-    if (n_dim < 2) {
-      return("a list")
-    } else if (n_dim == 2) {
-      return("a list matrix")
-    } else {
-      return("a list array")
-    }
-  }
-
-  type <- switch(type,
-    logical = "a logical %s",
-    integer = "an integer %s",
-    numeric = , # nolint
-    double = "a double %s",
-    complex = "a complex %s",
-    character = "a character %s",
-    raw = "a raw %s",
-    type = paste0("a ", type, " %s")
-  )
-
-  if (n_dim < 2) {
-    kind <- "vector"
-  } else if (n_dim == 2) {
-    kind <- "matrix"
-  } else {
-    kind <- "array"
-  }
-  sprintf(type, kind)
-}
-
-# Used in building `friendly_type_of()` above
-.rlang_as_friendly_type <- function(type) {
-  switch(type,
-    list = "a list",
-    NULL = "NULL",
-    environment = "an environment",
-    externalptr = "a pointer",
-    weakref = "a weak reference",
-    S4 = "an S4 object",
-    name = , # nolint
-    symbol = "a symbol",
-    language = "a call",
-    pairlist = "a pairlist node",
-    expression = "an expression vector",
-    char = "an internal string",
-    promise = "an internal promise",
-    ... = "an internal dots object",
-    any = "an internal `any` object",
-    bytecode = "an internal bytecode object",
-    primitive = , # nolint
-    builtin = , # nolint
-    special = "a primitive function",
-    closure = "a function",
-    type
-  )
-}
-
-# Used in building `friendly_type_of()` above
-.rlang_stop_unexpected_typeof <- function(x, call = rlang::caller_env()) {
-  rlang::abort(
-    sprintf("Unexpected type <%s>.", typeof(x)),
-    call = call
-  )
-}
-
-#' @param x The object type which does not conform to `what`. Its
-#'   `friendly_type_of()` is taken and mentioned in the error message.
-#' @param what The friendly expected type.
-#' @param ... Arguments passed to [abort()].
-#' @inheritParams args_error_context
-#' @noRd
-stop_input_type <- function(x,
-                            what,
-                            ...,
-                            arg = rlang::caller_arg(x),
-                            call = rlang::caller_env()) {
-  # From compat-cli.R
-  format_arg <- rlang::env_get(
-    nm = "format_arg",
-    last = topenv(),
-    default = NULL
-  )
-  if (!is.function(format_arg)) {
-    format_arg <- function(x) sprintf("`%s`", x)
-  }
-
-  msg <- sprintf(
-    "%s must be %s, not %s.",
-    format_arg(arg),
-    what,
-    friendly_type_of(x)
-  )
-  rlang::abort(msg, ..., call = call)
 }

R/compat_friendly_type.R

@@ -34,36 +34,26 @@ convert_dtm_to_dtc <- function(dtm) {
 
 #' Extract Argument Name from an Expression
 #'
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' This function is *deprecated*, please use `rlang::caller_arg()` instead.
+#'
 #' @param expr An expression created inside a function using `substitute()`
 #'
 #'
 #' @return `character` vector
 #'
-#' @keywords dev_utility
-#' @family dev_utility
+#' @keywords deprecated
+#' @family deprecated
 #'
 #' @export
 arg_name <- function(expr) { # nolint
-  lifecycle::deprecate_soft(
+  lifecycle::deprecate_stop(
     when = "1.1.0",
     what = "admiraldev::arg_name()",
-    details = "This function was primarily used in error messaging, and can be
-               replaced with `assert_*(x, arg_name = rlang::caller_arg(x))`"
+    with = "rlang::caller_arg()"
   )
-
-  if (length(expr) == 1L && is.symbol(expr)) {
-    deparse(expr)
-  } else if (length(expr) == 2L &&
-    (expr[[1L]] == quote(enexpr) || expr[[1L]] == quote(rlang::enexpr)) &&
-    is.symbol(expr[[2L]])) {
-    deparse(expr[[2L]])
-  } else if (is.call(expr) && length(expr) >= 2 && is.symbol(expr[[2]])) {
-    deparse(expr[[2L]])
-  } else if (is.call(expr) && length(expr) >= 2 && is.call(expr[[2]])) {
-    arg_name(expr[[2L]])
-  } else {
-    abort(paste0("Could not extract argument name from `", deparse(expr), "`"))
-  }
 }
 
 #' Extract All Symbols from a List of Expressions
@@ -101,6 +91,11 @@ extract_vars <- function(x, side = "lhs") {
 
 #' Or
 #'
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' This function is *deprecated*. Please get in touch if you are using this function!
+#'
 #' @param lhs Any valid R expression
 #' @param rhs Any valid R expression
 #'
@@ -113,23 +108,48 @@ extract_vars <- function(x, side = "lhs") {
 #'
 #' @export
 #'
-#' @keywords dev_utility
-#' @family dev_utility
+#' @keywords deprecated
+#' @family deprecated
 `%or%` <- function(lhs, rhs) {
+  deprecate_inform(
+    when = "1.4.0",
+    what = "admiraldev::`%or%`()",
+    details = c(
+      x = "This message will turn into a warning at the beginning of 2027.",
+      i = "See admiral's deprecation guidance:
+              https://pharmaverse.github.io/admiraldev/dev/articles/programming_strategy.html#deprecation", # nolint
+      i = "Please get in touch if you are using this function!"
+    )
+  )
   tryCatch(lhs, error = function(e) rhs)
 }
 
 #' Valid Time Units
 #'
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' This function is *deprecated*. Please get in touch if you are using this function!
+#'
 #' Contains the acceptable character vector of valid time units
 #'
 #' @return A `character` vector of valid time units
 #'
 #' @export
 #'
-#' @keywords dev_utility
-#' @family dev_utility
+#' @keywords deprecated
+#' @family deprecated
 valid_time_units <- function() {
+  deprecate_inform(
+    when = "1.4.0",
+    what = "admiraldev::valid_time_units()",
+    details = c(
+      x = "This message will turn into a warning at the beginning of 2027.",
+      i = "See admiral's deprecation guidance:
+              https://pharmaverse.github.io/admiraldev/dev/articles/programming_strategy.html#deprecation", # nolint
+      i = "Please get in touch if you are using this function!"
+    )
+  )
   c("years", "months", "days", "hours", "minutes", "seconds")
 }