Closes #466 deprecation 2.0 (#467)

* docs: #466 deprecate 2.0 * docs: #466 unit tests and roxygen * chore: #466 news * chore: #466 pkgdown yml * Update vignettes/programming_strategy.Rmd Co-authored-by: Stefan Bundfuss <[email protected]> * Update vignettes/programming_strategy.Rmd Co-authored-by: Stefan Bundfuss <[email protected]> * Update vignettes/programming_strategy.Rmd Co-authored-by: Stefan Bundfuss <[email protected]> * Update vignettes/programming_strategy.Rmd Co-authored-by: Stefan Bundfuss <[email protected]> * Update vignettes/programming_strategy.Rmd Co-authored-by: Stefan Bundfuss <[email protected]> * feat: #466 inform function skeleton and tests * feat: looking at snapshot options with lifecycle * docs: #466 news entry for function and some general guidance for reference page * docs: #466 inserted details in guidance * docs: #466 feedback from review * docs: #466 more feedback adopted from review * docs: #466 lets read! * chore: #466 that lintr life * chore: #466 making it work again * chore: #466 style me baby!! * chore: #466 lints and docs * chore: #446 unclear on doc updates * docs: #466 wordsmithing fun for deprecation!! * chore: #466 styling and spelling * chore: #466 docs * chore: #466 namespace * feat: #466 arguments from lifecycle for environments * chore: #466 argument hell * feat: #466 include all arguments; todo: figure out NA issue * docs: #466 getting pretty; environment tweaks * documentation udpate * doc update * doc update * chore: #466 spelling * Update admiraldev.Rproj --------- Co-authored-by: Stefan Bundfuss <[email protected]> Co-authored-by: Daniel Sjoberg <[email protected]>
pharmaverse · Dec 23, 2024 · c0e266f · c0e266f
1 parent 6a074e3
commit c0e266f
Show file tree

Hide file tree

Showing 10 changed files with 328 additions and 47 deletions.
diff --git a/NAMESPACE b/NAMESPACE
@@ -33,6 +33,7 @@ export(backquote)
 export(contains_vars)
 export(convert_dtm_to_dtc)
 export(dataset_vignette)
+export(deprecate_inform)
 export(dquote)
 export(enumerate)
 export(expect_dfs_equal)
@@ -96,6 +97,7 @@ importFrom(dplyr,ungroup)
 importFrom(dplyr,union)
 importFrom(glue,glue)
 importFrom(glue,glue_collapse)
+importFrom(lifecycle,deprecate_soft)
 importFrom(lifecycle,deprecate_stop)
 importFrom(lifecycle,deprecate_warn)
 importFrom(lifecycle,deprecated)

diff --git a/NEWS.md b/NEWS.md
@@ -1,5 +1,10 @@
 # admiraldev (development version)
 
+## New Features
+
+- New Function `deprecate_inform()` is a wrapper around 
+  `lifecycle::deprecate_soft()` to allow for more control over messaging. (#466)
+
 ## Updates of Existing Functions
 
 - Objects passed to `assert_list_element()` via the `...` argument can now be
@@ -27,6 +32,7 @@ check whether the vector has a specific length. (#473)
   - Removed at v1.0.0 `assert_function_param()`
 
 ## Documentation
+  - Deprecation Strategy updated for the long haul! (#466)
 
 ## Other
 

diff --git a/R/admiraldev-package.R b/R/admiraldev-package.R
@@ -20,7 +20,7 @@
 #'             time_length %--% ymd ymd_hms weeks years hours minutes
 #' @importFrom tidyr drop_na nest pivot_longer pivot_wider unnest
 #' @importFrom tidyselect all_of contains vars_select
-#' @importFrom lifecycle deprecate_warn deprecated deprecate_stop
+#' @importFrom lifecycle deprecate_warn deprecated deprecate_stop deprecate_soft
 #' @importFrom cli cli_abort cli_div
 #' @importFrom glue glue glue_collapse
 "_PACKAGE"
diff --git a/R/lifecycle_admiral.R b/R/lifecycle_admiral.R
@@ -0,0 +1,50 @@
+#' Deprecation with Soft Message
+#'
+#' Wrapper around `lifecycle::deprecate_soft()` that messages users about
+#' deprecated features and functions instead of warning.
+#'
+#' @inheritParams lifecycle::deprecate_soft
+#'
+#' @return `NULL`, invisibly.
+#'
+#' @examples
+#' # A Phase 1 deprecated function with custom bulleted list:
+#' deprecate_inform(
+#'   when = "1.0.0",
+#'   what = "foo()",
+#'   details = c(
+#'     x = "This message will turn into a warning with release of x.y.z",
+#'     i = "See admiral's deprecation guidance:
+#' https://pharmaverse.github.io/admiraldev/dev/articles/programming_strategy.html#deprecation"
+#'   )
+#' )
+#'
+#' @keywords messages
+#' @family messages
+#'
+#'
+#' @export
+deprecate_inform <- function(
+    when,
+    what,
+    with = NULL,
+    details = NULL,
+    id = NULL,
+    env = rlang::caller_env(),
+    user_env = rlang::caller_env(2)) {
+  tryCatch(
+    lifecycle::deprecate_soft(
+      when = when,
+      what = what,
+      with = with,
+      details = details,
+      id = id,
+      env = env,
+      user_env = user_env
+    ),
+    warning = \(w) {
+      message(conditionMessage(w))
+      tryInvokeRestart("muffleWarning")
+    }
+  )
+}
diff --git a/_pkgdown.yml b/_pkgdown.yml
@@ -88,16 +88,23 @@ reference:
   desc: Utilities without a theme
   contents:
   - has_keyword('dev_utility')
+  - has_keyword('messages')
 
 - title: Deprecated
   desc: |
-    As `{admiral}` is still evolving, functions/arguments may need to be removed or replaced over time. In such cases, the function/argument will enter the following 6-month deprecation cycle:
+    Functions and arguments may need to be removed or replaced over time.
+    In such cases, the function or argument will enter a 3 year deprecation cycle.
+    The cycle will be tied as close as sensibly possible to a package release.
 
-    * In the first release (0-3 months), there will be a warning issued if you use the function/argument, but it will still be available to use.
-    * In the following release (3-6 months), an error will be produced if you use the function/argument.
-    * Finally, from the 3rd release (6 months) onwards, the function/argument will be removed from `{admiral}` and its documentation completely.
+    When a function is deprecated:
 
-    *Note: Guidance on replacement functionality can be found in the warning/error message produced or in the function's documentation.*
+    * In Year 1 there will be a message issued if you use the function/argument, but it will still be available to use.
+    * In Year 2 a warning will be produced if you use the function/argument, but it will still be available to use.
+    * In Year 3, an error will be produced if you use the function/argument and no longer be able to use.
+    * Finally, after 3 years, the function/argument and related documentation and tests will be removed from `{admiral}`.
+
+    *Note: Guidance on replacement functionality will be found in the message produced as well as in the function's
+    documentation*
 
     Below, you can find a list of functions in the process of being deprecated:
   contents:

diff --git a/inst/WORDLIST b/inst/WORDLIST
@@ -32,8 +32,8 @@ Modularity
 Mubasheer
 Neitmann
 OCCDS
-Ondrej
 ORCID
+Ondrej
 PHUSE
 PRs
 Pharma
@@ -45,12 +45,12 @@ README
 RStudio
 Rimler
 Roxygen
-Samia
 SDTM
+Samia
 Slama
 Syed
 TAs
-Thomas
+TBD
 TOC
 TTE
 USUBJID
@@ -65,7 +65,7 @@ admiraltemplate
 admiralxxx
 advs
 anonymized
-arg
+behaviour
 cmd
 codebase
 codeowner
@@ -94,6 +94,7 @@ pharmaverse
 pkgs
 pre
 proc
+programmatically
 quosures
 repo
 reproducibility

diff --git a/man/deprecate_inform.Rd b/man/deprecate_inform.Rd
diff --git a/tests/testthat/_snaps/lifecycle_admiral.md b/tests/testthat/_snaps/lifecycle_admiral.md
@@ -0,0 +1,30 @@
+# lifecycle_admiral Test 1:  Simple message is sent to user
+
+    Code
+      example_fun(data)
+    Message
+      `example_fun()` was deprecated in admiraldev 1.0.0.
+      i Please use `example_fun2()` instead.
+    Code
+      example_fun(data)
+    Message
+      `example_fun()` was deprecated in admiraldev 1.0.0.
+      i Please use `example_fun2()` instead.
+
+# lifecycle_admiral Test 2:  Spicier message is sent to user
+
+    Code
+      example_fun(data)
+    Message
+      `example_fun()` was deprecated in admiraldev 1.0.0.
+      i Please use `example_fun2()` instead.
+      x This message will turn into a warning with release of 1.1.0
+      i See admiral's deprecation guidance: https://pharmaverse.github.io/admiraldev/dev/articles/programming_strategy.html#deprecation
+    Code
+      example_fun(data)
+    Message
+      `example_fun()` was deprecated in admiraldev 1.0.0.
+      i Please use `example_fun2()` instead.
+      x This message will turn into a warning with release of 1.1.0
+      i See admiral's deprecation guidance: https://pharmaverse.github.io/admiraldev/dev/articles/programming_strategy.html#deprecation
+
diff --git a/tests/testthat/test-lifecycle_admiral.R b/tests/testthat/test-lifecycle_admiral.R
@@ -0,0 +1,50 @@
+## Test 1:  Message is sent to user ----
+test_that("lifecycle_admiral Test 1:  Simple message is sent to user", {
+  example_fun <- function(dataset) {
+    deprecate_inform(
+      when = "1.0.0",
+      what = "example_fun()",
+      with = "example_fun2()"
+    )
+    assert_data_frame(dataset, required_vars = exprs(STUDYID, USUBJID))
+  }
+
+  data <- dplyr::tribble(
+    ~STUDYID, ~USUBJID,
+    "xyz",    123,
+    "xyz",    456
+  )
+
+  expect_snapshot({
+    example_fun(data)
+    example_fun(data)
+  })
+})
+
+# Test 2:  Nicer message is sent to user ----
+test_that("lifecycle_admiral Test 2:  Spicier message is sent to user", {
+  example_fun <- function(dataset) {
+    deprecate_inform(
+      when = "1.0.0",
+      what = "example_fun()",
+      with = "example_fun2()",
+      details = c(
+        x = "This message will turn into a warning with release of 1.1.0",
+        i = "See admiral's deprecation guidance:
+                       https://pharmaverse.github.io/admiraldev/dev/articles/programming_strategy.html#deprecation" # nolint
+      )
+    )
+    assert_data_frame(dataset, required_vars = exprs(STUDYID, USUBJID))
+  }
+
+  data <- dplyr::tribble(
+    ~STUDYID, ~USUBJID,
+    "xyz",    123,
+    "xyz",    456
+  )
+
+  expect_snapshot({
+    example_fun(data)
+    example_fun(data)
+  })
+})