From ef2f6c545bf7b68fbbda8a3033a9891f47a1faaa Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Mon, 7 Oct 2024 01:40:10 +0000
Subject: [PATCH 01/34] docs: #466 deprecate 2.0

---
 vignettes/programming_strategy.Rmd | 45 +++++++++++++++++-------------
 1 file changed, 26 insertions(+), 19 deletions(-)

diff --git a/vignettes/programming_strategy.Rmd b/vignettes/programming_strategy.Rmd
index 1590892d..487d5683 100644
--- a/vignettes/programming_strategy.Rmd
+++ b/vignettes/programming_strategy.Rmd
@@ -559,25 +559,32 @@ See [Writing Unit Tests in {admiral}](unit_test_guidance.html#writing-unit-tests
 
 # Deprecation
 
-As `{admiral}` is still evolving, functions or arguments may need to be removed
-or replaced with more efficient options from one release to another. In such
-cases, the relevant function or argument must be marked as deprecated. This
-deprecation is done in three phases over our release cycles.
-
--  **Phase 1:** In the release where the identified function or argument is to
-be deprecated there will be a warning issued when using the function or argument
-using `deprecate_warn()`.
-
--  **Phase 2:** In the next release an error will be thrown using
-`deprecate_stop()`.
-
--  **Phase 3:** Finally in the 3rd release thereafter the function will be
-removed from the package altogether.
-
-Information about deprecation timelines must be added to the warning/error message.
-
-Note that the deprecation cycle time for a function or argument based on our
-current release schedule is 6 months.
+`{admiral}` has reached a level of maturity with the release of `1.0.0` in December 2023.
+The below deprecation strategy provides stability to users while allowing admiral developers
+the ability to remove and update the code base in the coming days.
+
+- **Phase 1:** In the release where the identified function or argument is to
+be deprecated, there will be a message issued when using the function or argument
+using `deprecate_nicely()`. This message will appear to the user for _two years_.  The
+message will include the date this message will run for and a recommendation on which 
+function or argument to change to in their code.
+
+- **Phase 2:** After _two years_ and in the closet next release, a warning will be 
+issued when using the function or argument using `deprecate_warn()`. This warning 
+message will appear to the user for _one year_.  The message will include the date this 
+warning message will run for and a recommendation on which function or argument 
+to change to in their code.
+
+- **Phase 3:** After _one year_ and in the closest next release, an error will be thrown
+using the function or argument using `deprecate_stop()` and follow similar process
+for Phase 1 and Phase 2.
+
+- **Phase 4:** Finally four years from the time of being identified for deprecation, the
+function or argument will be completely removed from `{admiral}`.
+
+**Note:** Major/Minor release make the most sense for deprecation updates. However, if
+a release cycle becomes multiple years, then patch releases should be considered to
+help keep `{admiral}` neat and tidy!
 
 ## Documentation
 

From 5c00f05bd87fff0d32ccf16e55d1d9085dd85540 Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Tue, 8 Oct 2024 19:29:50 +0000
Subject: [PATCH 02/34] docs: #466 unit tests and roxygen

---
 vignettes/programming_strategy.Rmd | 75 ++++++++++++++++++++++--------
 1 file changed, 56 insertions(+), 19 deletions(-)

diff --git a/vignettes/programming_strategy.Rmd b/vignettes/programming_strategy.Rmd
index 487d5683..4ebf3dd6 100644
--- a/vignettes/programming_strategy.Rmd
+++ b/vignettes/programming_strategy.Rmd
@@ -561,15 +561,15 @@ See [Writing Unit Tests in {admiral}](unit_test_guidance.html#writing-unit-tests
 
 `{admiral}` has reached a level of maturity with the release of `1.0.0` in December 2023.
 The below deprecation strategy provides stability to users while allowing admiral developers
-the ability to remove and update the code base in the coming days.
+the ability to remove and update the codebase in the coming days.
 
 - **Phase 1:** In the release where the identified function or argument is to
 be deprecated, there will be a message issued when using the function or argument
-using `deprecate_nicely()`. This message will appear to the user for _two years_.  The
+using `deprecate_inform()`. This message will appear to the user for _one year_.  The
 message will include the date this message will run for and a recommendation on which 
 function or argument to change to in their code.
 
-- **Phase 2:** After _two years_ and in the closet next release, a warning will be 
+- **Phase 2:** After _one year_ and in the closet next release, a warning will be 
 issued when using the function or argument using `deprecate_warn()`. This warning 
 message will appear to the user for _one year_.  The message will include the date this 
 warning message will run for and a recommendation on which function or argument 
@@ -579,13 +579,16 @@ to change to in their code.
 using the function or argument using `deprecate_stop()` and follow similar process
 for Phase 1 and Phase 2.
 
-- **Phase 4:** Finally four years from the time of being identified for deprecation, the
+- **Phase 4:** Finally after three years from the time of being identified for deprecation, the
 function or argument will be completely removed from `{admiral}`.
 
-**Note:** Major/Minor release make the most sense for deprecation updates. However, if
+**NB:** Major/Minor release make the most sense for deprecation updates. However, if
 a release cycle becomes multiple years, then patch releases should be considered to
 help keep `{admiral}` neat and tidy!
 
+**NB:** Take care with `News.md` entries for deprecation as the person continuing this
+process might not be you!
+
 ## Documentation
 
 If a function or argument is removed, the documentation must be updated to
@@ -595,7 +598,7 @@ function/argument should be used instead.
 The documentation will be updated at:
 
 + the description level for a function, 
-+ the `@keywords` and`@family` roxygen tags will be replaced with `deprecated`
++ the `@keywords` and `@family` roxygen tags will be replaced with `deprecated`
 
     ```{r, eval=FALSE}
 #' Title of the function
@@ -619,22 +622,36 @@ The documentation will be updated at:
     @param old_param *Deprecated*, please use `new_param` instead.
     ```
 
-## Handling of Warning and Error
+## Handling of Messages, Warnings and Errors
 
 When a function or argument is deprecated, the function must be updated to issue
-a warning or error using `deprecate_warn()` and `deprecate_stop()`,
-respectively, as described above.
+a message, warning or error using `deprecate_inform()`, `deprecate_warn()` or 
+`deprecate_stop()`, respectively, as described above.
 
 There should be a test case added in the test file of the function that checks
-whether this warning/error is issued as appropriate when using the deprecated
+whether this message/warning/error is issued as appropriate when using the deprecated
 function or argument.
 
 ### Function
 
-In the initial release in which a function is deprecated the original function
-body must be replaced with a call to `deprecate_warn()` and subsequently all
+**Phase 1:** In the initial release in which a function is deprecated the original function
+body must be replaced with a call to `deprecate_inform()` and subsequently all
 arguments should be passed on to the new function.
 
+```r
+fun_xxx <- function(dataset, some_param, other_param) {
+  deprecate_inform("x.y.z", "fun_xxx()", "new_fun_xxx()")
+  new_fun_xxx(
+    dataset = dataset,
+    some_param = some_param,
+    other_param = other_param
+  )
+}
+```
+**Phase 2:** In the next year/closest release in which a function is deprecated 
+the original function body must be replaced with a call to `deprecate_warn()` and 
+subsequently all arguments should be passed on to the new function.
+
 ```r
 fun_xxx <- function(dataset, some_param, other_param) {
   deprecate_warn("x.y.z", "fun_xxx()", "new_fun_xxx()")
@@ -646,7 +663,7 @@ fun_xxx <- function(dataset, some_param, other_param) {
 }
 ```
 
-In the following release the function body should be changed to just include a call
+**Phase 3:** In the following release the function body should be changed to just include a call
 to `deprecate_stop()`.
 
 ```r
@@ -655,21 +672,28 @@ fun_xxx <- function(dataset, some_param, other_param) {
 }
 ```
 
-Finally, in the next release the function should be removed from the package.
+**Phase 4:** Finally, in the next release the function should be removed from the package.
 
 ### Argument
 
-If an argument is removed and is not replaced, an **error** must be generated:
+**Phase 1:** If the argument is renamed or replaced, a **message** must be issued and the
+new argument takes the value of the old argument until the next release. Note:
+arguments which are not passed as `exprs()` argument (e.g. `new_var = VAR1` or
+`filter = AVAL >10`) will need to be quoted.
 
-```
+``` 
 ### BEGIN DEPRECATION
   if (!missing(old_param)) {
-    deprecate_stop("x.y.z", "fun_xxx(old_param = )", "fun_xxx(new_param = )")
+    deprecate_inform("x.y.z", "fun_xxx(old_param = )", "fun_xxx(new_param = )")
+    # old_param is given using exprs()
+    new_param <- old_param
+    # old_param is NOT given using exprs()
+    new_param <- enexpr(old_param)
   }
 ### END DEPRECATION
 ```
 
-If the argument is renamed or replaced, a **warning** must be issued and the
+**Phase 2:** If the argument is renamed or replaced, a **warning** must be issued and the
 new argument takes the value of the old argument until the next release. Note:
 arguments which are not passed as `exprs()` argument (e.g. `new_var = VAR1` or
 `filter = AVAL >10`) will need to be quoted.
@@ -686,9 +710,22 @@ arguments which are not passed as `exprs()` argument (e.g. `new_var = VAR1` or
 ### END DEPRECATION
 ```
 
+**Phase 3:**  If an argument is removed and is not replaced, an **error** must be generated:
+
+```
+### BEGIN DEPRECATION
+  if (!missing(old_param)) {
+    deprecate_stop("x.y.z", "fun_xxx(old_param = )", "fun_xxx(new_param = )")
+  }
+### END DEPRECATION
+```
+
+
+
 ## Unit Testing
 
-Unit tests for deprecated functions and arguments must be added to the test file [^1] of the function to ensure that a warning or error is issued.
+Unit tests for deprecated functions and arguments must be added to the test 
+file [^1] of the function to ensure that a warning or error is issued.
 
 [^1]: For example, if `derive_var_example()` is going to be deprecated and
 it is defined in `examples.R`, the unit tests are in

From a78fc84fe2086f940e0e2e42a1406f93999167db Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Tue, 8 Oct 2024 19:31:49 +0000
Subject: [PATCH 03/34] chore: #466 news

---
 NEWS.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/NEWS.md b/NEWS.md
index be4cbab7..f469c9e1 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -17,6 +17,7 @@
   - Removed at v1.0.0 `assert_function_param()`
 
 ## Documentation
+  - Deprecation Strategy updated for the long haul! (#466)
 
 ## Other
 

From ead0e130e7f04488956db702254a788e0bbe6c38 Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Tue, 8 Oct 2024 19:34:57 +0000
Subject: [PATCH 04/34] chore: #466 pkgdown yml

---
 _pkgdown.yml | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/_pkgdown.yml b/_pkgdown.yml
index 7d62bcf6..30d3cd76 100644
--- a/_pkgdown.yml
+++ b/_pkgdown.yml
@@ -91,11 +91,12 @@ reference:
 
 - 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:
+    As `{admiral}` is still evolving, functions/arguments may need to be removed or replaced over time. In such cases, the function/argument will enter a 3 year deprecation cycle:
 
-    * 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.
+    * In the first release (1 year), there will be a message issued if you use the function/argument, but it will still be available to use.
+    * In the following release (1 year), an warning will be produced if you use the function/argument.
+    * In the following release (1 year), an error will be produced if you use the function/argument.
+    * Finally, after 3 years onwards, the function/argument will be removed from `{admiral}` and its documentation completely.
 
     *Note: Guidance on replacement functionality can be found in the warning/error message produced or in the function's documentation.*
 

From 823ff6c799eedbed9ab76adc9819c79ca3b92e5a Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Wed, 9 Oct 2024 10:31:20 -0400
Subject: [PATCH 05/34] Update vignettes/programming_strategy.Rmd

Co-authored-by: Stefan Bundfuss <80953585+bundfussr@users.noreply.github.com>
---
 vignettes/programming_strategy.Rmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/vignettes/programming_strategy.Rmd b/vignettes/programming_strategy.Rmd
index 4ebf3dd6..9d0ea1df 100644
--- a/vignettes/programming_strategy.Rmd
+++ b/vignettes/programming_strategy.Rmd
@@ -576,7 +576,7 @@ warning message will run for and a recommendation on which function or argument
 to change to in their code.
 
 - **Phase 3:** After _one year_ and in the closest next release, an error will be thrown
-using the function or argument using `deprecate_stop()` and follow similar process
+when using the function or argument using `deprecate_stop()` and follow similar process
 for Phase 1 and Phase 2.
 
 - **Phase 4:** Finally after three years from the time of being identified for deprecation, the

From 56eec0364474b348bf198b1395633ff4598c077b Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Wed, 9 Oct 2024 10:38:14 -0400
Subject: [PATCH 06/34] Update vignettes/programming_strategy.Rmd

Co-authored-by: Stefan Bundfuss <80953585+bundfussr@users.noreply.github.com>
---
 vignettes/programming_strategy.Rmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/vignettes/programming_strategy.Rmd b/vignettes/programming_strategy.Rmd
index 9d0ea1df..34d5e9c4 100644
--- a/vignettes/programming_strategy.Rmd
+++ b/vignettes/programming_strategy.Rmd
@@ -586,7 +586,7 @@ function or argument will be completely removed from `{admiral}`.
 a release cycle becomes multiple years, then patch releases should be considered to
 help keep `{admiral}` neat and tidy!
 
-**NB:** Take care with `News.md` entries for deprecation as the person continuing this
+**NB:** Take care with `NEWS.md` entries for deprecation as the person continuing this
 process might not be you!
 
 ## Documentation

From 76e4a131f7cbf009ded2e69400d8ea8e126d594c Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Wed, 9 Oct 2024 10:38:29 -0400
Subject: [PATCH 07/34] Update vignettes/programming_strategy.Rmd

Co-authored-by: Stefan Bundfuss <80953585+bundfussr@users.noreply.github.com>
---
 vignettes/programming_strategy.Rmd | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/vignettes/programming_strategy.Rmd b/vignettes/programming_strategy.Rmd
index 34d5e9c4..3532c821 100644
--- a/vignettes/programming_strategy.Rmd
+++ b/vignettes/programming_strategy.Rmd
@@ -649,8 +649,7 @@ fun_xxx <- function(dataset, some_param, other_param) {
 }
 ```
 **Phase 2:** In the next year/closest release in which a function is deprecated 
-the original function body must be replaced with a call to `deprecate_warn()` and 
-subsequently all arguments should be passed on to the new function.
+the call to `deprecate_inform()` must be replaced with a call to `deprecate_warn()`.
 
 ```r
 fun_xxx <- function(dataset, some_param, other_param) {

From c9304fdcab69b4a424cf663927f8d70981371453 Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Wed, 9 Oct 2024 10:39:09 -0400
Subject: [PATCH 08/34] Update vignettes/programming_strategy.Rmd

Co-authored-by: Stefan Bundfuss <80953585+bundfussr@users.noreply.github.com>
---
 vignettes/programming_strategy.Rmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/vignettes/programming_strategy.Rmd b/vignettes/programming_strategy.Rmd
index 3532c821..b4a0ea57 100644
--- a/vignettes/programming_strategy.Rmd
+++ b/vignettes/programming_strategy.Rmd
@@ -724,7 +724,7 @@ arguments which are not passed as `exprs()` argument (e.g. `new_var = VAR1` or
 ## Unit Testing
 
 Unit tests for deprecated functions and arguments must be added to the test 
-file [^1] of the function to ensure that a warning or error is issued.
+file [^1] of the function to ensure that a message, warning, or error is issued.
 
 [^1]: For example, if `derive_var_example()` is going to be deprecated and
 it is defined in `examples.R`, the unit tests are in

From f0d67efeb17d094972a06c12b5513f67789f924f Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Wed, 9 Oct 2024 10:39:19 -0400
Subject: [PATCH 09/34] Update vignettes/programming_strategy.Rmd

Co-authored-by: Stefan Bundfuss <80953585+bundfussr@users.noreply.github.com>
---
 vignettes/programming_strategy.Rmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/vignettes/programming_strategy.Rmd b/vignettes/programming_strategy.Rmd
index b4a0ea57..a4e1847d 100644
--- a/vignettes/programming_strategy.Rmd
+++ b/vignettes/programming_strategy.Rmd
@@ -619,7 +619,7 @@ The documentation will be updated at:
 + the `@param` level for a argument.
 
     ```
-    @param old_param *Deprecated*, please use `new_param` instead.
+    @param old_param `r lifecycle::badge("deprecated")` Please use `new_param` instead.
     ```
 
 ## Handling of Messages, Warnings and Errors

From 03dc9a011a17299ea0824ca39ef95b9a29b98b26 Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Fri, 15 Nov 2024 23:02:51 +0000
Subject: [PATCH 10/34] feat: #466 inform function skeleton and tests

---
 R/lifecycle_admiral.R                      | 23 +++++++++++
 tests/testthat/_snaps/lifecycle_admiral.md | 10 +++++
 tests/testthat/test-lifecycle_admiral.R    | 44 ++++++++++++++++++++++
 3 files changed, 77 insertions(+)
 create mode 100644 R/lifecycle_admiral.R
 create mode 100644 tests/testthat/_snaps/lifecycle_admiral.md
 create mode 100644 tests/testthat/test-lifecycle_admiral.R

diff --git a/R/lifecycle_admiral.R b/R/lifecycle_admiral.R
new file mode 100644
index 00000000..5e208041
--- /dev/null
+++ b/R/lifecycle_admiral.R
@@ -0,0 +1,23 @@
+#' Deprecation with Soft Message
+#'
+#' Wrapper around `lifecycle::deprecate_soft()`
+#'
+#' @param ...
+#'
+#' @return Return value of the expression
+#'
+#' @keywords messages
+#' @family messages
+#'
+#' @details
+#'
+#' @export
+deprecate_inform <- function(...) {
+  tryCatch(
+    lifecycle::deprecate_soft(...),
+    warning = \(w) {
+      message(conditionMessage(w))
+      tryInvokeRestart("muffleWarning")
+    }
+  )
+}
diff --git a/tests/testthat/_snaps/lifecycle_admiral.md b/tests/testthat/_snaps/lifecycle_admiral.md
new file mode 100644
index 00000000..71ef7b8f
--- /dev/null
+++ b/tests/testthat/_snaps/lifecycle_admiral.md
@@ -0,0 +1,10 @@
+# lifecycle_admiral Test 1:  Message is sent to user
+
+    Code
+      example_fun(data)
+
+# lifecycle_admiral Test 2:  Nicer message is sent to user
+
+    Code
+      example_fun(data)
+
diff --git a/tests/testthat/test-lifecycle_admiral.R b/tests/testthat/test-lifecycle_admiral.R
new file mode 100644
index 00000000..dcd42899
--- /dev/null
+++ b/tests/testthat/test-lifecycle_admiral.R
@@ -0,0 +1,44 @@
+## Test 1:  Message is sent to user ----
+test_that("lifecycle_admiral Test 1:  Message is sent to user", {
+  example_fun <- function(dataset) {
+    deprecate_inform("1.0.0", "example_fun()", "example_fun2()")
+    assert_data_frame(dataset, required_vars = exprs(STUDYID, USUBJID))
+  }
+
+  data <- dplyr::tribble(
+    ~STUDYID, ~USUBJID,
+    "xyz",    123,
+    "xyz",    456
+  )
+
+  withr::local_options(lifecycle_verbosity = "quiet")
+  expect_snapshot(
+    example_fun(data),
+  )
+
+})
+
+## Test 2:  Nicer message is sent to user ----
+test_that("lifecycle_admiral Test 2:  Nicer message is sent to user", {
+  example_fun <- function(dataset) {
+    deprecate_inform("1.0.0", "example_fun()", "example_fun2()",
+                     details = c(
+                       x = "Highly recommended to move to the suggested function",
+                       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
+  )
+
+  withr::local_options(lifecycle_verbosity = "quiet")
+  expect_snapshot(
+    example_fun(data),
+  )
+
+})

From 6c37370216b1e653bb4790e3fd1e13a14f2d7d3a Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Fri, 15 Nov 2024 23:07:13 +0000
Subject: [PATCH 11/34] feat: looking at snapshot options with lifecycle

---
 tests/testthat/_snaps/lifecycle_admiral.md | 8 ++++++++
 tests/testthat/test-lifecycle_admiral.R    | 6 +++---
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/tests/testthat/_snaps/lifecycle_admiral.md b/tests/testthat/_snaps/lifecycle_admiral.md
index 71ef7b8f..2d80021f 100644
--- a/tests/testthat/_snaps/lifecycle_admiral.md
+++ b/tests/testthat/_snaps/lifecycle_admiral.md
@@ -2,9 +2,17 @@
 
     Code
       example_fun(data)
+    Message
+      `example_fun()` was deprecated in admiraldev 1.0.0.
+      i Please use `example_fun2()` instead.
 
 # lifecycle_admiral Test 2:  Nicer 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
 
diff --git a/tests/testthat/test-lifecycle_admiral.R b/tests/testthat/test-lifecycle_admiral.R
index dcd42899..25916ddb 100644
--- a/tests/testthat/test-lifecycle_admiral.R
+++ b/tests/testthat/test-lifecycle_admiral.R
@@ -11,7 +11,7 @@ test_that("lifecycle_admiral Test 1:  Message is sent to user", {
     "xyz",    456
   )
 
-  withr::local_options(lifecycle_verbosity = "quiet")
+  #withr::local_options(lifecycle_verbosity = "quiet")
   expect_snapshot(
     example_fun(data),
   )
@@ -23,7 +23,7 @@ test_that("lifecycle_admiral Test 2:  Nicer message is sent to user", {
   example_fun <- function(dataset) {
     deprecate_inform("1.0.0", "example_fun()", "example_fun2()",
                      details = c(
-                       x = "Highly recommended to move to the suggested function",
+                       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
                      )
@@ -36,7 +36,7 @@ test_that("lifecycle_admiral Test 2:  Nicer message is sent to user", {
     "xyz",    456
   )
 
-  withr::local_options(lifecycle_verbosity = "quiet")
+  #withr::local_options(lifecycle_verbosity = "quiet")
   expect_snapshot(
     example_fun(data),
   )

From 94d4c79ae3dd00c695be927e22033abb3cc20113 Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Fri, 15 Nov 2024 23:20:40 +0000
Subject: [PATCH 12/34] docs: #466 news entry for function and some general
 guidance for reference page

---
 NEWS.md      |  5 +++++
 _pkgdown.yml | 14 +++++++++-----
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/NEWS.md b/NEWS.md
index 0c2762f9..d4b0367d 100644
--- 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
diff --git a/_pkgdown.yml b/_pkgdown.yml
index 30d3cd76..3ef8e3a2 100644
--- a/_pkgdown.yml
+++ b/_pkgdown.yml
@@ -91,12 +91,16 @@ reference:
 
 - 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 a 3 year deprecation cycle:
+    As `{admiral}` is still evolving, functions/arguments may need to be removed or replaced over time.
+    In such cases, the function/argument will enter a 3 year deprecation cycle. The cycle
+    will be tied as close as sensibly possible to a release.
 
-    * In the first release (1 year), there will be a message issued if you use the function/argument, but it will still be available to use.
-    * In the following release (1 year), an warning will be produced if you use the function/argument.
-    * In the following release (1 year), an error will be produced if you use the function/argument.
-    * Finally, after 3 years onwards, the function/argument will be removed from `{admiral}` and its documentation completely.
+    Once a function is deprecated:
+
+    * 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.
+    * In Year 3, an error will be produced if you use the function/argument.
+    * Finally, after 3 years, the function/argument and related documentation and tests will be removed from `{admiral}`.
 
     *Note: Guidance on replacement functionality can be found in the warning/error message produced or in the function's documentation.*
 

From 2ce81a7b4ed8e656065cbfd39298f3ae1997aefc Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Fri, 15 Nov 2024 23:24:34 +0000
Subject: [PATCH 13/34] docs: #466 inserted details in guidance

---
 vignettes/programming_strategy.Rmd | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/vignettes/programming_strategy.Rmd b/vignettes/programming_strategy.Rmd
index a4e1847d..0c03c473 100644
--- a/vignettes/programming_strategy.Rmd
+++ b/vignettes/programming_strategy.Rmd
@@ -644,8 +644,13 @@ fun_xxx <- function(dataset, some_param, other_param) {
   new_fun_xxx(
     dataset = dataset,
     some_param = some_param,
-    other_param = other_param
-  )
+    other_param = other_param,
+    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"
+              )  
+            ) 
 }
 ```
 **Phase 2:** In the next year/closest release in which a function is deprecated 

From 1582679f786fc688cd8ff2ca8bc5d36c61f19125 Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Fri, 15 Nov 2024 23:26:27 +0000
Subject: [PATCH 14/34] docs: #466 feedback from review

---
 _pkgdown.yml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/_pkgdown.yml b/_pkgdown.yml
index 3ef8e3a2..e7ce4494 100644
--- a/_pkgdown.yml
+++ b/_pkgdown.yml
@@ -91,9 +91,9 @@ reference:
 
 - 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 a 3 year deprecation cycle. The cycle
-    will be tied as close as sensibly possible to a release.
+    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 release.
 
     Once a function is deprecated:
 

From 9c973179f4c20ee7df396421daf187f8c9283356 Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Fri, 15 Nov 2024 23:32:00 +0000
Subject: [PATCH 15/34] docs: #466 more feedback adopted from review

---
 vignettes/programming_strategy.Rmd | 1 -
 1 file changed, 1 deletion(-)

diff --git a/vignettes/programming_strategy.Rmd b/vignettes/programming_strategy.Rmd
index 0c03c473..cf12712c 100644
--- a/vignettes/programming_strategy.Rmd
+++ b/vignettes/programming_strategy.Rmd
@@ -559,7 +559,6 @@ See [Writing Unit Tests in {admiral}](unit_test_guidance.html#writing-unit-tests
 
 # Deprecation
 
-`{admiral}` has reached a level of maturity with the release of `1.0.0` in December 2023.
 The below deprecation strategy provides stability to users while allowing admiral developers
 the ability to remove and update the codebase in the coming days.
 

From db723a942da6b89fe3046c7b87ceb5361176f2c6 Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Fri, 6 Dec 2024 01:56:27 +0000
Subject: [PATCH 16/34] docs: #466 lets read!

---
 NAMESPACE                          |  1 +
 R/lifecycle_admiral.R              | 20 +++++++++++++++---
 man/deprecate_inform.Rd            | 34 ++++++++++++++++++++++++++++++
 vignettes/programming_strategy.Rmd | 13 +++++++-----
 4 files changed, 60 insertions(+), 8 deletions(-)
 create mode 100644 man/deprecate_inform.Rd

diff --git a/NAMESPACE b/NAMESPACE
index 6624d0b6..6a2a0f11 100644
--- 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)
diff --git a/R/lifecycle_admiral.R b/R/lifecycle_admiral.R
index 5e208041..2eed720e 100644
--- a/R/lifecycle_admiral.R
+++ b/R/lifecycle_admiral.R
@@ -1,15 +1,29 @@
 #' Deprecation with Soft Message
 #'
-#' Wrapper around `lifecycle::deprecate_soft()`
+#' Wrapper around `lifecycle::deprecate_soft()`.
+#' See documentation for `lifecycle::deprecate_soft()` for argument use.
 #'
 #' @param ...
 #'
-#' @return Return value of the expression
+#' @return `NULL`, invisibly.
+#'
+#' @examples
+#' # A Phase 1 deprecated function with custom bulleted list:
+#' deprecate_warn(
+#'   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
 #'
-#' @details
 #'
 #' @export
 deprecate_inform <- function(...) {
diff --git a/man/deprecate_inform.Rd b/man/deprecate_inform.Rd
new file mode 100644
index 00000000..5195199a
--- /dev/null
+++ b/man/deprecate_inform.Rd
@@ -0,0 +1,34 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/lifecycle_admiral.R
+\name{deprecate_inform}
+\alias{deprecate_inform}
+\title{Deprecation with Soft Message}
+\usage{
+deprecate_inform(...)
+}
+\arguments{
+\item{...}{}
+}
+\value{
+\code{NULL}, invisibly.
+}
+\description{
+Wrapper around \code{lifecycle::deprecate_soft()}.
+See documentation for \code{lifecycle::deprecate_soft()} for argument use.
+}
+\examples{
+# A Phase 1 deprecated function with custom bulleted list:
+deprecate_warn(
+  when = "1.0.0",
+  what = "foo()",
+  details = c(
+    i = "See admiral's deprecation guidance:
+https://pharmaverse.github.io/admiraldev/dev/articles/programming_strategy.html#deprecation"
+)
+)
+
+
+
+}
+\concept{messages}
+\keyword{messages}
diff --git a/vignettes/programming_strategy.Rmd b/vignettes/programming_strategy.Rmd
index cf12712c..62797f17 100644
--- a/vignettes/programming_strategy.Rmd
+++ b/vignettes/programming_strategy.Rmd
@@ -639,17 +639,20 @@ arguments should be passed on to the new function.
 
 ```r
 fun_xxx <- function(dataset, some_param, other_param) {
-  deprecate_inform("x.y.z", "fun_xxx()", "new_fun_xxx()")
-  new_fun_xxx(
-    dataset = dataset,
-    some_param = some_param,
-    other_param = other_param,
+  deprecate_inform(
+    when = "x.y.z", 
+    what = "fun_xxx()", 
+    with = "new_fun_xxx()",
     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"
               )  
             ) 
+    function(
+    dataset = dataset,
+    some_param = some_param,
+    other_param = other_param)
 }
 ```
 **Phase 2:** In the next year/closest release in which a function is deprecated 

From ceff2f0da2393750b499db95ccf9f296c85f3955 Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Fri, 6 Dec 2024 01:59:40 +0000
Subject: [PATCH 17/34] chore: #466 that lintr life

---
 tests/testthat/test-lifecycle_admiral.R | 2 --
 1 file changed, 2 deletions(-)

diff --git a/tests/testthat/test-lifecycle_admiral.R b/tests/testthat/test-lifecycle_admiral.R
index 25916ddb..208f42e3 100644
--- a/tests/testthat/test-lifecycle_admiral.R
+++ b/tests/testthat/test-lifecycle_admiral.R
@@ -11,7 +11,6 @@ test_that("lifecycle_admiral Test 1:  Message is sent to user", {
     "xyz",    456
   )
 
-  #withr::local_options(lifecycle_verbosity = "quiet")
   expect_snapshot(
     example_fun(data),
   )
@@ -36,7 +35,6 @@ test_that("lifecycle_admiral Test 2:  Nicer message is sent to user", {
     "xyz",    456
   )
 
-  #withr::local_options(lifecycle_verbosity = "quiet")
   expect_snapshot(
     example_fun(data),
   )

From 9db16535756eb89bb6ed4c049875dc58328f7e27 Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Fri, 6 Dec 2024 02:08:34 +0000
Subject: [PATCH 18/34] chore: #466 making it work again

---
 R/lifecycle_admiral.R   | 2 +-
 man/deprecate_inform.Rd | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/R/lifecycle_admiral.R b/R/lifecycle_admiral.R
index 2eed720e..f4a694b6 100644
--- a/R/lifecycle_admiral.R
+++ b/R/lifecycle_admiral.R
@@ -3,7 +3,7 @@
 #' Wrapper around `lifecycle::deprecate_soft()`.
 #' See documentation for `lifecycle::deprecate_soft()` for argument use.
 #'
-#' @param ...
+#' @param ... See documentation for `lifecycle::deprecate_soft()` for argument use.
 #'
 #' @return `NULL`, invisibly.
 #'
diff --git a/man/deprecate_inform.Rd b/man/deprecate_inform.Rd
index 5195199a..2e753d2b 100644
--- a/man/deprecate_inform.Rd
+++ b/man/deprecate_inform.Rd
@@ -7,7 +7,7 @@
 deprecate_inform(...)
 }
 \arguments{
-\item{...}{}
+\item{...}{See documentation for \code{lifecycle::deprecate_soft()} for argument use.}
 }
 \value{
 \code{NULL}, invisibly.

From 445eb677c1f308a8ea45df27461a50f077f5a554 Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Fri, 6 Dec 2024 02:09:55 +0000
Subject: [PATCH 19/34] chore: #466 style me baby!!

---
 R/lifecycle_admiral.R                   |  6 ++----
 tests/testthat/test-lifecycle_admiral.R | 13 ++++++-------
 2 files changed, 8 insertions(+), 11 deletions(-)

diff --git a/R/lifecycle_admiral.R b/R/lifecycle_admiral.R
index f4a694b6..a13690c1 100644
--- a/R/lifecycle_admiral.R
+++ b/R/lifecycle_admiral.R
@@ -13,13 +13,11 @@
 #'   when = "1.0.0",
 #'   what = "foo()",
 #'   details = c(
-#     'x = "This message will turn into a warning with release of x.y.z",
+#'     #     '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
diff --git a/tests/testthat/test-lifecycle_admiral.R b/tests/testthat/test-lifecycle_admiral.R
index 208f42e3..eb3d210d 100644
--- a/tests/testthat/test-lifecycle_admiral.R
+++ b/tests/testthat/test-lifecycle_admiral.R
@@ -14,18 +14,18 @@ test_that("lifecycle_admiral Test 1:  Message is sent to user", {
   expect_snapshot(
     example_fun(data),
   )
-
 })
 
 ## Test 2:  Nicer message is sent to user ----
 test_that("lifecycle_admiral Test 2:  Nicer message is sent to user", {
   example_fun <- function(dataset) {
     deprecate_inform("1.0.0", "example_fun()", "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
-                     )
+      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))
   }
 
@@ -38,5 +38,4 @@ test_that("lifecycle_admiral Test 2:  Nicer message is sent to user", {
   expect_snapshot(
     example_fun(data),
   )
-
 })

From 672287a6152303b61769b28f9947f8f8afa40faf Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Fri, 6 Dec 2024 02:14:52 +0000
Subject: [PATCH 20/34] chore: #466 lints and docs

---
 R/lifecycle_admiral.R                   | 2 +-
 man/deprecate_inform.Rd                 | 5 ++---
 tests/testthat/test-lifecycle_admiral.R | 4 ++--
 3 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/R/lifecycle_admiral.R b/R/lifecycle_admiral.R
index a13690c1..ce4681c4 100644
--- a/R/lifecycle_admiral.R
+++ b/R/lifecycle_admiral.R
@@ -9,7 +9,7 @@
 #'
 #' @examples
 #' # A Phase 1 deprecated function with custom bulleted list:
-#' deprecate_warn(
+#' deprecate_inform(
 #'   when = "1.0.0",
 #'   what = "foo()",
 #'   details = c(
diff --git a/man/deprecate_inform.Rd b/man/deprecate_inform.Rd
index 2e753d2b..96c04211 100644
--- a/man/deprecate_inform.Rd
+++ b/man/deprecate_inform.Rd
@@ -22,12 +22,11 @@ deprecate_warn(
   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"
+  )
 )
-)
-
-
 
 }
 \concept{messages}
diff --git a/tests/testthat/test-lifecycle_admiral.R b/tests/testthat/test-lifecycle_admiral.R
index eb3d210d..56897f58 100644
--- a/tests/testthat/test-lifecycle_admiral.R
+++ b/tests/testthat/test-lifecycle_admiral.R
@@ -23,8 +23,8 @@ test_that("lifecycle_admiral Test 2:  Nicer message is sent to user", {
       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
+                       https://pharmaverse.github.io/admiraldev/dev/articles/programming_strategy.html#deprecation" # nolint
+      )
     )
     assert_data_frame(dataset, required_vars = exprs(STUDYID, USUBJID))
   }

From df5bfbe46886eb8b793a6b61587861e6d06f01d8 Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Fri, 6 Dec 2024 02:17:57 +0000
Subject: [PATCH 21/34] chore: #446 unclear on doc updates

---
 man/deprecate_inform.Rd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man/deprecate_inform.Rd b/man/deprecate_inform.Rd
index 96c04211..c745b477 100644
--- a/man/deprecate_inform.Rd
+++ b/man/deprecate_inform.Rd
@@ -18,7 +18,7 @@ See documentation for \code{lifecycle::deprecate_soft()} for argument use.
 }
 \examples{
 # A Phase 1 deprecated function with custom bulleted list:
-deprecate_warn(
+deprecate_inform(
   when = "1.0.0",
   what = "foo()",
   details = c(

From bcf839424c89443cb023b4e27bb9960fa41c89a1 Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Wed, 18 Dec 2024 23:10:43 +0000
Subject: [PATCH 22/34] docs: #466 wordsmithing fun for deprecation!!

---
 _pkgdown.yml                                  | 12 ++++---
 .../testthat/_snaps/lifecycle_admiral.new.md  | 30 ++++++++++++++++
 tests/testthat/test-lifecycle_admiral.R       | 19 +++++++----
 vignettes/programming_strategy.Rmd            | 34 +++++++++++--------
 4 files changed, 69 insertions(+), 26 deletions(-)
 create mode 100644 tests/testthat/_snaps/lifecycle_admiral.new.md

diff --git a/_pkgdown.yml b/_pkgdown.yml
index e7ce4494..367c0667 100644
--- a/_pkgdown.yml
+++ b/_pkgdown.yml
@@ -88,21 +88,23 @@ reference:
   desc: Utilities without a theme
   contents:
   - has_keyword('dev_utility')
+  - has_keyword('messages')
 
 - title: Deprecated
   desc: |
     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 release.
+    The cycle will be tied as close as sensibly possible to a package release.
 
-    Once a function is deprecated:
+    When a function is deprecated:
 
     * 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.
-    * In Year 3, an error will be produced if you use the function/argument.
+    * 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 can be found in the warning/error message produced or in the function's documentation.*
+    *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/tests/testthat/_snaps/lifecycle_admiral.new.md b/tests/testthat/_snaps/lifecycle_admiral.new.md
new file mode 100644
index 00000000..7a2b1185
--- /dev/null
+++ b/tests/testthat/_snaps/lifecycle_admiral.new.md
@@ -0,0 +1,30 @@
+# lifecycle_admiral Test 1:  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:  Nicer 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
index 56897f58..b8dc66c5 100644
--- a/tests/testthat/test-lifecycle_admiral.R
+++ b/tests/testthat/test-lifecycle_admiral.R
@@ -11,12 +11,15 @@ test_that("lifecycle_admiral Test 1:  Message is sent to user", {
     "xyz",    456
   )
 
-  expect_snapshot(
-    example_fun(data),
-  )
+  expect_snapshot({
+   example_fun(data)
+   example_fun(data)
+  })
+
+
 })
 
-## Test 2:  Nicer message is sent to user ----
+# Test 2:  Nicer message is sent to user ----
 test_that("lifecycle_admiral Test 2:  Nicer message is sent to user", {
   example_fun <- function(dataset) {
     deprecate_inform("1.0.0", "example_fun()", "example_fun2()",
@@ -35,7 +38,9 @@ test_that("lifecycle_admiral Test 2:  Nicer message is sent to user", {
     "xyz",    456
   )
 
-  expect_snapshot(
-    example_fun(data),
-  )
+  expect_snapshot({
+    example_fun(data)
+    example_fun(data)
+  })
+
 })
diff --git a/vignettes/programming_strategy.Rmd b/vignettes/programming_strategy.Rmd
index 62797f17..f69d2fda 100644
--- a/vignettes/programming_strategy.Rmd
+++ b/vignettes/programming_strategy.Rmd
@@ -565,14 +565,13 @@ the ability to remove and update the codebase in the coming days.
 - **Phase 1:** In the release where the identified function or argument is to
 be deprecated, there will be a message issued when using the function or argument
 using `deprecate_inform()`. This message will appear to the user for _one year_.  The
-message will include the date this message will run for and a recommendation on which 
-function or argument to change to in their code.
+message will include the a recommendation on which function or argument to change 
+to in their code.
 
 - **Phase 2:** After _one year_ and in the closet next release, a warning will be 
 issued when using the function or argument using `deprecate_warn()`. This warning 
-message will appear to the user for _one year_.  The message will include the date this 
-warning message will run for and a recommendation on which function or argument 
-to change to in their code.
+message will appear to the user for _one year_.  The message a recommendation on which 
+function or argument to change to in their code.
 
 - **Phase 3:** After _one year_ and in the closest next release, an error will be thrown
 when using the function or argument using `deprecate_stop()` and follow similar process
@@ -585,7 +584,7 @@ function or argument will be completely removed from `{admiral}`.
 a release cycle becomes multiple years, then patch releases should be considered to
 help keep `{admiral}` neat and tidy!
 
-**NB:** Take care with `NEWS.md` entries for deprecation as the person continuing this
+**NB:** Take care with the `NEWS.md` entries around deprecation as the person continuing this
 process might not be you!
 
 ## Documentation
@@ -594,7 +593,7 @@ If a function or argument is removed, the documentation must be updated to
 indicate the function or the argument is now deprecated and which new
 function/argument should be used instead.
 
-The documentation will be updated at:
+The documentation will be updated at Phase 2:
 
 + the description level for a function, 
 + the `@keywords` and `@family` roxygen tags will be replaced with `deprecated`
@@ -608,18 +607,20 @@ The documentation will be updated at:
 #' This function is *deprecated*, please use `new_fun()` instead.
 #' .
 #' @family deprecated
-#'
 #' @keywords deprecated
-#' .
     ``` 
 
-+ the `@examples` section should be removed.
+Example for documentation at the argument level
 
 + the `@param` level for a argument.
 
-    ```
-    @param old_param `r lifecycle::badge("deprecated")` Please use `new_param` instead.
-    ```
+  ```
+  @param old_param `r lifecycle::badge("deprecated")` Please use `new_param` instead.
+  ```
+
+The documentation will be further updated at Phase 3:
+
++ the `@examples` section should be removed.
 
 ## Handling of Messages, Warnings and Errors
 
@@ -744,6 +745,11 @@ respectively. The unit-test should follow the corresponding format, per the
 
 ### For Deprecated Functions that Issues a Warning (Phase 1)
 
+TBD
+
+
+### For Deprecated Functions that Issues a Warning (Phase 2)
+
 A unit test like the following must be added.
 ```
 ## Test #: deprecation warning if function is called ----
@@ -765,7 +771,7 @@ In the existing unit tests the call of the deprecated function need to be enclos
 The `regexpr` argument must be specified to ensure that only the deprecation
 warning is suppressed.
 
-### For Deprecated Functions that Issues an Error (Phase 2)
+### For Deprecated Functions that Issues an Error (Phase 3)
 
 A unit test like the following must be added.
 ```

From f59f52e3589f86b80995ab3c1e59aaf32ad7fa3a Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Wed, 18 Dec 2024 23:18:01 +0000
Subject: [PATCH 23/34] chore: #466 styling and spelling

---
 inst/WORDLIST                           | 7 +++----
 tests/testthat/test-lifecycle_admiral.R | 7 ++-----
 2 files changed, 5 insertions(+), 9 deletions(-)

diff --git a/inst/WORDLIST b/inst/WORDLIST
index 450a8236..d2099f9c 100644
--- 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,6 @@ admiraltemplate
 admiralxxx
 advs
 anonymized
-arg
 cmd
 codebase
 codeowner
diff --git a/tests/testthat/test-lifecycle_admiral.R b/tests/testthat/test-lifecycle_admiral.R
index b8dc66c5..590a5952 100644
--- a/tests/testthat/test-lifecycle_admiral.R
+++ b/tests/testthat/test-lifecycle_admiral.R
@@ -12,11 +12,9 @@ test_that("lifecycle_admiral Test 1:  Message is sent to user", {
   )
 
   expect_snapshot({
-   example_fun(data)
-   example_fun(data)
+    example_fun(data)
+    example_fun(data)
   })
-
-
 })
 
 # Test 2:  Nicer message is sent to user ----
@@ -42,5 +40,4 @@ test_that("lifecycle_admiral Test 2:  Nicer message is sent to user", {
     example_fun(data)
     example_fun(data)
   })
-
 })

From f26e63024630d35d81dbf7d9aea43acef05c3927 Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Thu, 19 Dec 2024 21:45:28 +0000
Subject: [PATCH 24/34] chore: #466 docs

---
 R/lifecycle_admiral.R   | 1 -
 man/deprecate_inform.Rd | 1 -
 2 files changed, 2 deletions(-)

diff --git a/R/lifecycle_admiral.R b/R/lifecycle_admiral.R
index ce4681c4..21db1c93 100644
--- a/R/lifecycle_admiral.R
+++ b/R/lifecycle_admiral.R
@@ -1,7 +1,6 @@
 #' Deprecation with Soft Message
 #'
 #' Wrapper around `lifecycle::deprecate_soft()`.
-#' See documentation for `lifecycle::deprecate_soft()` for argument use.
 #'
 #' @param ... See documentation for `lifecycle::deprecate_soft()` for argument use.
 #'
diff --git a/man/deprecate_inform.Rd b/man/deprecate_inform.Rd
index c745b477..bc8b4ec8 100644
--- a/man/deprecate_inform.Rd
+++ b/man/deprecate_inform.Rd
@@ -14,7 +14,6 @@ deprecate_inform(...)
 }
 \description{
 Wrapper around \code{lifecycle::deprecate_soft()}.
-See documentation for \code{lifecycle::deprecate_soft()} for argument use.
 }
 \examples{
 # A Phase 1 deprecated function with custom bulleted list:

From 112dadedbef7e0fb3330a0e3c15700bb42ff528b Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Thu, 19 Dec 2024 21:47:57 +0000
Subject: [PATCH 25/34] chore: #466 namespace

---
 NAMESPACE              | 1 +
 R/admiraldev-package.R | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/NAMESPACE b/NAMESPACE
index 6a2a0f11..56d10a09 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -97,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/R/admiraldev-package.R b/R/admiraldev-package.R
index a478d0a9..76b4a51d 100644
--- 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"

From 90dd2b32157e7ef16a70519e3f20dabf663d942c Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Fri, 20 Dec 2024 01:08:06 +0000
Subject: [PATCH 26/34] feat: #466 arguments from lifecycle for environments

---
 R/lifecycle_admiral.R              | 11 +++++++++--
 man/deprecate_inform.Rd            |  6 +++++-
 vignettes/programming_strategy.Rmd |  5 ++---
 3 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/R/lifecycle_admiral.R b/R/lifecycle_admiral.R
index 21db1c93..c3e63ff7 100644
--- a/R/lifecycle_admiral.R
+++ b/R/lifecycle_admiral.R
@@ -2,7 +2,11 @@
 #'
 #' Wrapper around `lifecycle::deprecate_soft()`.
 #'
-#' @param ... See documentation for `lifecycle::deprecate_soft()` for argument use.
+#' @param env See documentation for `lifecycle::deprecate_soft()`.
+#'
+#' @param user_env See documentation for `lifecycle::deprecate_soft()`.
+#'
+#' @param ... See documentation for `lifecycle::deprecate_soft()` for additional argument use.
 #'
 #' @return `NULL`, invisibly.
 #'
@@ -25,7 +29,10 @@
 #' @export
 deprecate_inform <- function(...) {
   tryCatch(
-    lifecycle::deprecate_soft(...),
+    lifecycle::deprecate_soft(
+      env = caller_env(),
+      user_env = caller_env(),
+      ...),
     warning = \(w) {
       message(conditionMessage(w))
       tryInvokeRestart("muffleWarning")
diff --git a/man/deprecate_inform.Rd b/man/deprecate_inform.Rd
index bc8b4ec8..362d6806 100644
--- a/man/deprecate_inform.Rd
+++ b/man/deprecate_inform.Rd
@@ -7,7 +7,11 @@
 deprecate_inform(...)
 }
 \arguments{
-\item{...}{See documentation for \code{lifecycle::deprecate_soft()} for argument use.}
+\item{...}{See documentation for \code{lifecycle::deprecate_soft()} for additional argument use.}
+
+\item{env}{See documentation for \code{lifecycle::deprecate_soft()}.}
+
+\item{user_env}{See documentation for \code{lifecycle::deprecate_soft()}.}
 }
 \value{
 \code{NULL}, invisibly.
diff --git a/vignettes/programming_strategy.Rmd b/vignettes/programming_strategy.Rmd
index f69d2fda..8f384b9d 100644
--- a/vignettes/programming_strategy.Rmd
+++ b/vignettes/programming_strategy.Rmd
@@ -650,10 +650,9 @@ fun_xxx <- function(dataset, some_param, other_param) {
               https://pharmaverse.github.io/admiraldev/dev/articles/programming_strategy.html#deprecation"
               )  
             ) 
-    function(
     dataset = dataset,
     some_param = some_param,
-    other_param = other_param)
+    other_param = other_param
 }
 ```
 **Phase 2:** In the next year/closest release in which a function is deprecated 
@@ -662,7 +661,7 @@ the call to `deprecate_inform()` must be replaced with a call to `deprecate_warn
 ```r
 fun_xxx <- function(dataset, some_param, other_param) {
   deprecate_warn("x.y.z", "fun_xxx()", "new_fun_xxx()")
-  new_fun_xxx(
+  fun_xxx(
     dataset = dataset,
     some_param = some_param,
     other_param = other_param

From dd48670bedfe59ed254dfe2bd102ec2b95620133 Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Fri, 20 Dec 2024 01:14:04 +0000
Subject: [PATCH 27/34] chore: #466 argument hell

---
 R/lifecycle_admiral.R   | 9 +++++++--
 man/deprecate_inform.Rd | 6 +++---
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/R/lifecycle_admiral.R b/R/lifecycle_admiral.R
index c3e63ff7..8c232dab 100644
--- a/R/lifecycle_admiral.R
+++ b/R/lifecycle_admiral.R
@@ -8,6 +8,8 @@
 #'
 #' @param ... See documentation for `lifecycle::deprecate_soft()` for additional argument use.
 #'
+#'
+#'
 #' @return `NULL`, invisibly.
 #'
 #' @examples
@@ -27,11 +29,14 @@
 #'
 #'
 #' @export
-deprecate_inform <- function(...) {
+deprecate_inform <- function(
+    env = caller_env(),
+    user_env = caller_env(2),
+    ...) {
   tryCatch(
     lifecycle::deprecate_soft(
       env = caller_env(),
-      user_env = caller_env(),
+      user_env = caller_env(2),
       ...),
     warning = \(w) {
       message(conditionMessage(w))
diff --git a/man/deprecate_inform.Rd b/man/deprecate_inform.Rd
index 362d6806..ad62b110 100644
--- a/man/deprecate_inform.Rd
+++ b/man/deprecate_inform.Rd
@@ -4,14 +4,14 @@
 \alias{deprecate_inform}
 \title{Deprecation with Soft Message}
 \usage{
-deprecate_inform(...)
+deprecate_inform(env = caller_env(), user_env = caller_env(2), ...)
 }
 \arguments{
-\item{...}{See documentation for \code{lifecycle::deprecate_soft()} for additional argument use.}
-
 \item{env}{See documentation for \code{lifecycle::deprecate_soft()}.}
 
 \item{user_env}{See documentation for \code{lifecycle::deprecate_soft()}.}
+
+\item{...}{See documentation for \code{lifecycle::deprecate_soft()} for additional argument use.}
 }
 \value{
 \code{NULL}, invisibly.

From 9afde36592bbb39d3af46c6eece28cef41c62af1 Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Fri, 20 Dec 2024 19:30:00 +0000
Subject: [PATCH 28/34] feat: #466 include all arguments; todo: figure out NA
 issue

---
 R/lifecycle_admiral.R                         | 31 ++++++++++++-------
 man/deprecate_inform.Rd                       | 24 +++++++++++---
 tests/testthat/_snaps/lifecycle_admiral.md    | 20 +++++++++---
 .../testthat/_snaps/lifecycle_admiral.new.md  | 30 ------------------
 tests/testthat/test-lifecycle_admiral.R       | 15 ++++++---
 5 files changed, 66 insertions(+), 54 deletions(-)
 delete mode 100644 tests/testthat/_snaps/lifecycle_admiral.new.md

diff --git a/R/lifecycle_admiral.R b/R/lifecycle_admiral.R
index 8c232dab..eb379a3d 100644
--- a/R/lifecycle_admiral.R
+++ b/R/lifecycle_admiral.R
@@ -2,14 +2,13 @@
 #'
 #' Wrapper around `lifecycle::deprecate_soft()`.
 #'
+#' @param when See documentation for `lifecycle::deprecate_soft()`.
+#' @param what See documentation for `lifecycle::deprecate_soft()`.
+#' @param with See documentation for `lifecycle::deprecate_soft()`.
+#' @param details See documentation for `lifecycle::deprecate_soft()`.
+#' @param id See documentation for `lifecycle::deprecate_soft()`.
 #' @param env See documentation for `lifecycle::deprecate_soft()`.
-#'
 #' @param user_env See documentation for `lifecycle::deprecate_soft()`.
-#'
-#' @param ... See documentation for `lifecycle::deprecate_soft()` for additional argument use.
-#'
-#'
-#'
 #' @return `NULL`, invisibly.
 #'
 #' @examples
@@ -18,7 +17,7 @@
 #'   when = "1.0.0",
 #'   what = "foo()",
 #'   details = c(
-#'     #     'x = "This message will turn into a warning with release of x.y.z",
+#'     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"
 #'   )
@@ -30,14 +29,22 @@
 #'
 #' @export
 deprecate_inform <- function(
+    when,
+    what,
+    with = NULL,
+    details = NULL,
+    id = NULL,
     env = caller_env(),
-    user_env = caller_env(2),
-    ...) {
+    user_env = caller_env(2)) {
   tryCatch(
     lifecycle::deprecate_soft(
-      env = caller_env(),
-      user_env = caller_env(2),
-      ...),
+      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/man/deprecate_inform.Rd b/man/deprecate_inform.Rd
index ad62b110..13ca1020 100644
--- a/man/deprecate_inform.Rd
+++ b/man/deprecate_inform.Rd
@@ -4,14 +4,30 @@
 \alias{deprecate_inform}
 \title{Deprecation with Soft Message}
 \usage{
-deprecate_inform(env = caller_env(), user_env = caller_env(2), ...)
+deprecate_inform(
+  when,
+  what,
+  with = NULL,
+  details = NULL,
+  id = NULL,
+  env = caller_env(),
+  user_env = caller_env(2)
+)
 }
 \arguments{
+\item{when}{See documentation for \code{lifecycle::deprecate_soft()}.}
+
+\item{what}{See documentation for \code{lifecycle::deprecate_soft()}.}
+
+\item{with}{See documentation for \code{lifecycle::deprecate_soft()}.}
+
+\item{details}{See documentation for \code{lifecycle::deprecate_soft()}.}
+
+\item{id}{See documentation for \code{lifecycle::deprecate_soft()}.}
+
 \item{env}{See documentation for \code{lifecycle::deprecate_soft()}.}
 
 \item{user_env}{See documentation for \code{lifecycle::deprecate_soft()}.}
-
-\item{...}{See documentation for \code{lifecycle::deprecate_soft()} for additional argument use.}
 }
 \value{
 \code{NULL}, invisibly.
@@ -25,7 +41,7 @@ deprecate_inform(
   when = "1.0.0",
   what = "foo()",
   details = c(
-    #     'x = "This message will turn into a warning with release of x.y.z",
+    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"
   )
diff --git a/tests/testthat/_snaps/lifecycle_admiral.md b/tests/testthat/_snaps/lifecycle_admiral.md
index 2d80021f..ae19f17d 100644
--- a/tests/testthat/_snaps/lifecycle_admiral.md
+++ b/tests/testthat/_snaps/lifecycle_admiral.md
@@ -1,17 +1,29 @@
-# lifecycle_admiral Test 1:  Message is sent to user
+# lifecycle_admiral Test 1:  Simple message is sent to user
 
     Code
       example_fun(data)
     Message
-      `example_fun()` was deprecated in admiraldev 1.0.0.
+      `example_fun()` was deprecated in <NA> 1.0.0.
+      i Please use `example_fun2()` instead.
+    Code
+      example_fun(data)
+    Message
+      `example_fun()` was deprecated in <NA> 1.0.0.
       i Please use `example_fun2()` instead.
 
-# lifecycle_admiral Test 2:  Nicer message is sent to user
+# lifecycle_admiral Test 2:  Spicier message is sent to user
 
     Code
       example_fun(data)
     Message
-      `example_fun()` was deprecated in admiraldev 1.0.0.
+      `example_fun()` was deprecated in <NA> 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 <NA> 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/_snaps/lifecycle_admiral.new.md b/tests/testthat/_snaps/lifecycle_admiral.new.md
deleted file mode 100644
index 7a2b1185..00000000
--- a/tests/testthat/_snaps/lifecycle_admiral.new.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# lifecycle_admiral Test 1:  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:  Nicer 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
index 590a5952..a1198d88 100644
--- a/tests/testthat/test-lifecycle_admiral.R
+++ b/tests/testthat/test-lifecycle_admiral.R
@@ -1,7 +1,11 @@
 ## Test 1:  Message is sent to user ----
-test_that("lifecycle_admiral 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("1.0.0", "example_fun()", "example_fun2()")
+    deprecate_inform(
+      when = "1.0.0",
+      what = "example_fun()",
+      with = "example_fun2()"
+      )
     assert_data_frame(dataset, required_vars = exprs(STUDYID, USUBJID))
   }
 
@@ -18,9 +22,12 @@ test_that("lifecycle_admiral Test 1:  Message is sent to user", {
 })
 
 # Test 2:  Nicer message is sent to user ----
-test_that("lifecycle_admiral 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("1.0.0", "example_fun()", "example_fun2()",
+    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:

From e29b860f389848e6545ebe0a18d58f5154ab40e9 Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Sun, 22 Dec 2024 20:39:44 +0000
Subject: [PATCH 29/34] docs: #466 getting pretty; environment tweaks

---
 R/lifecycle_admiral.R                      | 7 ++++---
 man/deprecate_inform.Rd                    | 4 ++--
 tests/testthat/_snaps/lifecycle_admiral.md | 8 ++++----
 tests/testthat/test-lifecycle_admiral.R    | 2 +-
 4 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/R/lifecycle_admiral.R b/R/lifecycle_admiral.R
index eb379a3d..fdc4e934 100644
--- a/R/lifecycle_admiral.R
+++ b/R/lifecycle_admiral.R
@@ -34,8 +34,8 @@ deprecate_inform <- function(
     with = NULL,
     details = NULL,
     id = NULL,
-    env = caller_env(),
-    user_env = caller_env(2)) {
+    env = rlang::caller_env(),
+    user_env = rlang::caller_env(2)) {
   tryCatch(
     lifecycle::deprecate_soft(
       when = when,
@@ -44,7 +44,8 @@ deprecate_inform <- function(
       details = details,
       id = id,
       env = env,
-      user_env = user_env),
+      user_env = user_env
+    ),
     warning = \(w) {
       message(conditionMessage(w))
       tryInvokeRestart("muffleWarning")
diff --git a/man/deprecate_inform.Rd b/man/deprecate_inform.Rd
index 13ca1020..70c6ee16 100644
--- a/man/deprecate_inform.Rd
+++ b/man/deprecate_inform.Rd
@@ -10,8 +10,8 @@ deprecate_inform(
   with = NULL,
   details = NULL,
   id = NULL,
-  env = caller_env(),
-  user_env = caller_env(2)
+  env = rlang::caller_env(),
+  user_env = rlang::caller_env(2)
 )
 }
 \arguments{
diff --git a/tests/testthat/_snaps/lifecycle_admiral.md b/tests/testthat/_snaps/lifecycle_admiral.md
index ae19f17d..01cd2a7d 100644
--- a/tests/testthat/_snaps/lifecycle_admiral.md
+++ b/tests/testthat/_snaps/lifecycle_admiral.md
@@ -3,12 +3,12 @@
     Code
       example_fun(data)
     Message
-      `example_fun()` was deprecated in <NA> 1.0.0.
+      `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 <NA> 1.0.0.
+      `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
@@ -16,14 +16,14 @@
     Code
       example_fun(data)
     Message
-      `example_fun()` was deprecated in <NA> 1.0.0.
+      `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 <NA> 1.0.0.
+      `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
index a1198d88..9be7c7af 100644
--- a/tests/testthat/test-lifecycle_admiral.R
+++ b/tests/testthat/test-lifecycle_admiral.R
@@ -5,7 +5,7 @@ test_that("lifecycle_admiral Test 1:  Simple message is sent to user", {
       when = "1.0.0",
       what = "example_fun()",
       with = "example_fun2()"
-      )
+    )
     assert_data_frame(dataset, required_vars = exprs(STUDYID, USUBJID))
   }
 

From 1fdaab56567ba9e1dbdb8f1fd48a2455eb7f87fe Mon Sep 17 00:00:00 2001
From: Daniel Sjoberg <danield.sjoberg@gmail.com>
Date: Sun, 22 Dec 2024 19:19:15 -0800
Subject: [PATCH 30/34] documentation udpate

---
 R/lifecycle_admiral.R   |  9 ++-------
 admiraldev.Rproj        |  1 +
 man/deprecate_inform.Rd | 41 ++++++++++++++++++++++++++++++++++-------
 3 files changed, 37 insertions(+), 14 deletions(-)

diff --git a/R/lifecycle_admiral.R b/R/lifecycle_admiral.R
index fdc4e934..6fe0ea4c 100644
--- a/R/lifecycle_admiral.R
+++ b/R/lifecycle_admiral.R
@@ -2,13 +2,8 @@
 #'
 #' Wrapper around `lifecycle::deprecate_soft()`.
 #'
-#' @param when See documentation for `lifecycle::deprecate_soft()`.
-#' @param what See documentation for `lifecycle::deprecate_soft()`.
-#' @param with See documentation for `lifecycle::deprecate_soft()`.
-#' @param details See documentation for `lifecycle::deprecate_soft()`.
-#' @param id See documentation for `lifecycle::deprecate_soft()`.
-#' @param env See documentation for `lifecycle::deprecate_soft()`.
-#' @param user_env See documentation for `lifecycle::deprecate_soft()`.
+#' @inheritParams lifecycle::deprecate_soft
+#'
 #' @return `NULL`, invisibly.
 #'
 #' @examples
diff --git a/admiraldev.Rproj b/admiraldev.Rproj
index 934df488..21f9d0e0 100644
--- a/admiraldev.Rproj
+++ b/admiraldev.Rproj
@@ -1,4 +1,5 @@
 Version: 1.0
+ProjectId: cdbce8e6-0934-430c-a76c-0c8cffbb9203
 
 RestoreWorkspace: No
 SaveWorkspace: No
diff --git a/man/deprecate_inform.Rd b/man/deprecate_inform.Rd
index 70c6ee16..95639f2c 100644
--- a/man/deprecate_inform.Rd
+++ b/man/deprecate_inform.Rd
@@ -15,19 +15,46 @@ deprecate_inform(
 )
 }
 \arguments{
-\item{when}{See documentation for \code{lifecycle::deprecate_soft()}.}
+\item{when}{A string giving the version when the behaviour was deprecated.}
 
-\item{what}{See documentation for \code{lifecycle::deprecate_soft()}.}
+\item{what}{A string describing what is deprecated:
+\itemize{
+\item Deprecate a whole function with \code{"foo()"}.
+\item Deprecate an argument with \code{"foo(arg)"}.
+\item Partially deprecate an argument with
+\code{"foo(arg = 'must be a scalar integer')"}.
+\item Deprecate anything else with a custom message by wrapping it in \code{I()}.
+}
+
+You can optionally supply the namespace: \code{"ns::foo()"}, but this is
+usually not needed as it will be inferred from the caller environment.}
+
+\item{with}{An optional string giving a recommended replacement for the
+deprecated behaviour. This takes the same form as \code{what}.}
 
-\item{with}{See documentation for \code{lifecycle::deprecate_soft()}.}
+\item{details}{In most cases the deprecation message can be
+automatically generated from \code{with}. When it can't, use \code{details}
+to provide a hand-written message.
 
-\item{details}{See documentation for \code{lifecycle::deprecate_soft()}.}
+\code{details} can either be a single string or a character vector,
+which will be converted to a \link[cli:cli_bullets]{bulleted list}.
+By default, info bullets are used. Provide a named vectors to
+override.}
 
-\item{id}{See documentation for \code{lifecycle::deprecate_soft()}.}
+\item{id}{The id of the deprecation. A warning is issued only once
+for each \code{id}. Defaults to the generated message, but you should
+give a unique ID when the message in \code{details} is built
+programmatically and depends on inputs, or when you'd like to
+deprecate multiple functions but warn only once for all of them.}
 
-\item{env}{See documentation for \code{lifecycle::deprecate_soft()}.}
+\item{env, user_env}{Pair of environments that define where \verb{deprecate_*()}
+was called (used to determine the package name) and where the function
+called the deprecating function was called (used to determine if
+\code{deprecate_soft()} should message).
 
-\item{user_env}{See documentation for \code{lifecycle::deprecate_soft()}.}
+These are only needed if you're calling \verb{deprecate_*()} from an internal
+helper, in which case you should forward \code{env = caller_env()} and
+\code{user_env = caller_env(2)}.}
 }
 \value{
 \code{NULL}, invisibly.

From 92f4989079ac45506bf6d2de0a668bae0f1273af Mon Sep 17 00:00:00 2001
From: Daniel Sjoberg <danield.sjoberg@gmail.com>
Date: Sun, 22 Dec 2024 19:20:32 -0800
Subject: [PATCH 31/34] doc update

---
 R/lifecycle_admiral.R   | 3 ++-
 man/deprecate_inform.Rd | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/R/lifecycle_admiral.R b/R/lifecycle_admiral.R
index 6fe0ea4c..7096ee83 100644
--- a/R/lifecycle_admiral.R
+++ b/R/lifecycle_admiral.R
@@ -1,6 +1,7 @@
 #' Deprecation with Soft Message
 #'
-#' Wrapper around `lifecycle::deprecate_soft()`.
+#' Wrapper around `lifecycle::deprecate_soft()` that messages users about
+#' deprecationed features and functions instead of warning.
 #'
 #' @inheritParams lifecycle::deprecate_soft
 #'
diff --git a/man/deprecate_inform.Rd b/man/deprecate_inform.Rd
index 95639f2c..fe49653b 100644
--- a/man/deprecate_inform.Rd
+++ b/man/deprecate_inform.Rd
@@ -60,7 +60,8 @@ helper, in which case you should forward \code{env = caller_env()} and
 \code{NULL}, invisibly.
 }
 \description{
-Wrapper around \code{lifecycle::deprecate_soft()}.
+Wrapper around \code{lifecycle::deprecate_soft()} that messages users about
+deprecationed features and functions instead of warning.
 }
 \examples{
 # A Phase 1 deprecated function with custom bulleted list:

From b0274269396ed089d4c0e35177fa0b49d263c01c Mon Sep 17 00:00:00 2001
From: Daniel Sjoberg <danield.sjoberg@gmail.com>
Date: Sun, 22 Dec 2024 19:20:48 -0800
Subject: [PATCH 32/34] doc update

---
 R/lifecycle_admiral.R   | 2 +-
 man/deprecate_inform.Rd | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/R/lifecycle_admiral.R b/R/lifecycle_admiral.R
index 7096ee83..fa9c6970 100644
--- a/R/lifecycle_admiral.R
+++ b/R/lifecycle_admiral.R
@@ -1,7 +1,7 @@
 #' Deprecation with Soft Message
 #'
 #' Wrapper around `lifecycle::deprecate_soft()` that messages users about
-#' deprecationed features and functions instead of warning.
+#' deprecated features and functions instead of warning.
 #'
 #' @inheritParams lifecycle::deprecate_soft
 #'
diff --git a/man/deprecate_inform.Rd b/man/deprecate_inform.Rd
index fe49653b..7c00fe9c 100644
--- a/man/deprecate_inform.Rd
+++ b/man/deprecate_inform.Rd
@@ -61,7 +61,7 @@ helper, in which case you should forward \code{env = caller_env()} and
 }
 \description{
 Wrapper around \code{lifecycle::deprecate_soft()} that messages users about
-deprecationed features and functions instead of warning.
+deprecated features and functions instead of warning.
 }
 \examples{
 # A Phase 1 deprecated function with custom bulleted list:

From 569cf71301e1b86d75088851deb7436d3e4a6e5d Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Mon, 23 Dec 2024 18:09:02 +0000
Subject: [PATCH 33/34] chore: #466 spelling

---
 inst/WORDLIST | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/inst/WORDLIST b/inst/WORDLIST
index d2099f9c..f6b4f8cd 100644
--- a/inst/WORDLIST
+++ b/inst/WORDLIST
@@ -65,6 +65,7 @@ admiraltemplate
 admiralxxx
 advs
 anonymized
+behaviour
 cmd
 codebase
 codeowner
@@ -93,6 +94,7 @@ pharmaverse
 pkgs
 pre
 proc
+programmatically
 quosures
 repo
 reproducibility

From 23a17bda37be7b7f30da591a9ea8a76e97bb0bee Mon Sep 17 00:00:00 2001
From: Ben Straub <ben.x.straub@gsk.com>
Date: Mon, 23 Dec 2024 13:11:57 -0500
Subject: [PATCH 34/34] Update admiraldev.Rproj

---
 admiraldev.Rproj | 1 -
 1 file changed, 1 deletion(-)

diff --git a/admiraldev.Rproj b/admiraldev.Rproj
index 21f9d0e0..934df488 100644
--- a/admiraldev.Rproj
+++ b/admiraldev.Rproj
@@ -1,5 +1,4 @@
 Version: 1.0
-ProjectId: cdbce8e6-0934-430c-a76c-0c8cffbb9203
 
 RestoreWorkspace: No
 SaveWorkspace: No