Deprecate signal_stage()

NEWS.md

@@ -1,6 +1,6 @@
 # lifecycle (development version)
 
-* The condition generated by `signal_stage()` no longer directly exposes fields such as `cnd$package` and `cnd$function_nm` (#195).
+* `signal_stage()` is now deprecated. This was never hooked up to anything, and our original ideas for it never panned out, so the overhead it entails no longer feels worth it.
 
 * `deprecate_soft()` and `deprecate_warn()` are faster thanks to some internal refactoring (#191, #194, #195, #201).
 

R/deprecate.R

@@ -122,8 +122,6 @@ deprecate_soft <- function(
     )
   )
 
-  signal_stage("deprecated", what)
-
   verbosity <- lifecycle_verbosity()
   direct <- is_direct(user_env)
 
@@ -180,8 +178,6 @@ deprecate_warn <- function(
     )
   )
 
-  signal_stage("deprecated", what)
-
   verbosity <- lifecycle_verbosity()
 
   invisible(switch(
@@ -223,7 +219,6 @@ deprecate_stop <- function(
     env,
     signaller = "deprecate_stop"
   )
-  signal_stage("deprecated", what)
   deprecate_stop0(msg)
 }
 
@@ -238,6 +233,12 @@ deprecate_warn0 <- function(
   trace_env = caller_env(),
   user_env = caller_env(2)
 ) {
+  # declare(
+  #   params(msg = lazy)
+  # )
+
+  # `msg` is passed lazily for performance reasons! Avoid evaluating it before
+  # checking if we can early exit using the `id`.
   id <- id %||% paste_line(msg)
   if (!always && !needs_warning(id, call = call)) {
     return()

R/signal.R → R/deprecated-signal.R

@@ -1,29 +1,45 @@
-#' Signal other experimental or superseded features
+#' Deprecated functions for signalling lifecycle stages
 #'
 #' @description
-#' `r badge("experimental")`
-#'
-#' `signal_stage()` allows you to signal life cycle stages other than
-#' deprecation (for which you should use [deprecate_warn()] and friends).
-#' There is no behaviour associated with this signal, but in the future
-#' we will provide tools to log and report on usage of experimental and
-#' superseded functions.
-#'
-#' @param stage Life cycle stage, either "experimental" or "superseded".
-#' @param what String describing what feature the stage applies too, using
-#'   the same syntax as [deprecate_warn()].
-#' @param with An optional string giving a recommended replacement for
-#'   a superseded function.
-#' @param env Environment used to determine where `signal_stage()`
-#'   was called, used to determine the package name).
+#' `r badge("deprecated")`
+#' @name deprecated-signallers
+#' @keywords internal
+NULL
+
+#' @rdname deprecated-signallers
 #' @export
-#' @examples
-#' foofy <- function(x, y, z) {
-#'   signal_stage("experimental", "foofy()")
-#'   x + y / z
-#' }
-#' foofy(1, 2, 3)
 signal_stage <- function(stage, what, with = NULL, env = caller_env()) {
+  deprecate_soft(
+    "1.1.0",
+    what = "signal_stage()",
+    id = "lifecycle_signal_stage"
+  )
+  signal_stage_impl(stage, what, with, env)
+}
+
+#' @rdname deprecated-signallers
+#' @export
+signal_experimental <- function(when, what, env = caller_env()) {
+  deprecate_soft(
+    "1.1.0",
+    what = "signal_experimental()",
+    id = "lifecycle_signal_experimental"
+  )
+  signal_stage_impl("experimental", what, with = NULL, env = env)
+}
+
+#' @rdname deprecated-signallers
+#' @export
+signal_superseded <- function(when, what, env = caller_env()) {
+  deprecate_soft(
+    "1.1.0",
+    what = "signal_superseded()",
+    id = "lifecycle_signal_superseded"
+  )
+  signal_stage_impl("superseded", what, with = NULL, env = env)
+}
+
+signal_stage_impl <- function(stage, what, with, env) {
   stage <- arg_match0(stage, c("experimental", "superseded", "deprecated"))
   cnd <- new_lifecycle_stage_cnd(stage, what, with, env)
   cnd_signal(cnd)
@@ -35,8 +51,6 @@ new_lifecycle_stage_cnd <- function(stage, what, with, env) {
   out
 }
 
-# We could export this if packages have a need to capture a lifecycle
-# condition and manipulate this data to generate their own custom message
 lifecycle_stage_cnd_data <- function(cnd) {
   stage <- cnd$stage
   what <- cnd$what
@@ -77,19 +91,3 @@ lifecycle_stage_cnd_data <- function(cnd) {
 conditionMessage.lifecycle_stage <- function(c) {
   lifecycle_stage_cnd_data(c)$message
 }
-
-#' Deprecated functions for signalling experimental and lifecycle stages
-#'
-#' @description
-#' `r badge("deprecated")`
-#' Please use [signal_stage()] instead
-#' @keywords internal
-#' @export
-signal_experimental <- function(when, what, env = caller_env()) {
-  signal_stage("experimental", what, env = env)
-}
-#' @rdname signal_experimental
-#' @export
-signal_superseded <- function(when, what, env = caller_env()) {
-  signal_stage("superseded", what, env = env)
-}

tests/testthat/_snaps/deprecate.md

@@ -189,14 +189,14 @@
 # lifecycle message is never generated when an `id` is supplied and we've already warned
 
     Code
-      deprecate_soft(when = stop("when"), what = I("needed by signal_stage()"), with = stop(
-        "with"), details = stop("details"), env = stop("env"), id = "test")
+      deprecate_soft(when = stop("when"), what = stop("what"), with = stop("with"),
+      details = stop("details"), env = stop("env"), id = "test")
 
 ---
 
     Code
-      deprecate_warn(when = stop("when"), what = I("needed by signal_stage()"), with = stop(
-        "with"), details = stop("details"), env = stop("env"), id = "test")
+      deprecate_warn(when = stop("when"), what = stop("what"), with = stop("with"),
+      details = stop("details"), env = stop("env"), id = "test")
 
 # needs_warning works as expected
 

tests/testthat/_snaps/signal.md → tests/testthat/_snaps/deprecated-signal.md

@@ -22,3 +22,27 @@
       <lifecycle_stage: foo(bar) is superseded
       Please use the `baz` argument instead.>
 
+# `signal_stage()` and friends are deprecated
+
+    Code
+      signal_stage("superseded", "foo()", "bar()")
+    Condition
+      Warning:
+      `signal_stage()` was deprecated in lifecycle 1.1.0.
+
+---
+
+    Code
+      signal_experimental("1.1.0", "foo()")
+    Condition
+      Warning:
+      `signal_experimental()` was deprecated in lifecycle 1.1.0.
+
+---
+
+    Code
+      signal_superseded("1.1.0", "foo()")
+    Condition
+      Warning:
+      `signal_superseded()` was deprecated in lifecycle 1.1.0.
+

tests/testthat/_snaps/lifecycle.md

@@ -0,0 +1,31 @@
+# deprecation warnings are not displayed again
+
+    Code
+      wrn
+    Output
+      <warning/lifecycle_warning_deprecated>
+      Warning:
+      `foo()` was deprecated in lifecycle 1.0.0.
+      This warning is displayed once per session.
+      Call `lifecycle::last_lifecycle_warnings()` to see where this warning was generated.
+
+---
+
+    Code
+      wrn
+    Output
+      <warning/lifecycle_warning_deprecated>
+      Warning:
+      `foo()` was deprecated in lifecycle 1.0.0.
+      Call `lifecycle::last_lifecycle_warnings()` to see where this warning was generated.
+
+---
+
+    Code
+      wrn
+    Output
+      <warning/lifecycle_warning_deprecated>
+      Warning:
+      `foo()` was deprecated in lifecycle 1.0.0.
+      Call `lifecycle::last_lifecycle_warnings()` to see where this warning was generated.
+

tests/testthat/test-deprecate.R

@@ -229,7 +229,7 @@ test_that("lifecycle message is never generated when an `id` is supplied and we'
   expect_snapshot({
     deprecate_soft(
       when = stop("when"),
-      what = I("needed by signal_stage()"),
+      what = stop("what"),
       with = stop("with"),
       details = stop("details"),
       env = stop("env"),
@@ -239,7 +239,7 @@ test_that("lifecycle message is never generated when an `id` is supplied and we'
   expect_snapshot({
     deprecate_warn(
       when = stop("when"),
-      what = I("needed by signal_stage()"),
+      what = stop("what"),
       with = stop("with"),
       details = stop("details"),
       env = stop("env"),

tests/testthat/test-signal.R → tests/testthat/test-deprecated-signal.R

@@ -1,4 +1,6 @@
 test_that("signal stage captures desired data", {
+  local_options(lifecycle_verbosity = "quiet")
+
   f <- function() {
     signal_stage("experimental", "pkg::foo(bar = 'baz')")
   }
@@ -13,15 +15,31 @@ test_that("signal stage captures desired data", {
 })
 
 test_that("signal generates user friendly message", {
+  local_options(lifecycle_verbosity = "quiet")
+
   expect_snapshot({
     (expect_condition(signal_stage("experimental", "foo()")))
     (expect_condition(signal_stage("superseded", "foo(bar)")))
   })
 })
 
 test_that("signal_stage supports with", {
+  local_options(lifecycle_verbosity = "quiet")
+
   expect_snapshot({
     (expect_condition(signal_stage("superseded", "foo()", "bar()")))
     (expect_condition(signal_stage("superseded", "foo(bar=)", "foo(baz=)")))
   })
 })
+
+test_that("`signal_stage()` and friends are deprecated", {
+  expect_snapshot({
+    signal_stage("superseded", "foo()", "bar()")
+  })
+  expect_snapshot({
+    signal_experimental("1.1.0", "foo()")
+  })
+  expect_snapshot({
+    signal_superseded("1.1.0", "foo()")
+  })
+})

tests/testthat/test-lifecycle.R

@@ -57,24 +57,41 @@ test_that("soft-deprecation warnings are issued when called from child of global
 })
 
 test_that("deprecation warnings are not displayed again", {
-  local_options(lifecycle_verbosity = NULL)
   local_interactive()
+  on.exit(env_unbind(deprecation_env, c("once-per-session", "unconditional")))
 
-  wrn <- catch_cnd(
-    deprecate_warn("1.0.0", "foo()", id = "once-per-session-note"),
-    classes = "warning"
-  )
-  footer <- cnd_footer(wrn)
-  expect_true(is_character(footer) && any(grepl("once per session", footer)))
+  # With `"default"` - warning only shown once per session
+  local_options(lifecycle_verbosity = "default")
+
+  retired <- function() {
+    deprecate_warn("1.0.0", "foo()", id = "once-per-session")
+  }
+
+  # First and only time shows "once per session" message
+  wrn <- catch_cnd(retired(), classes = "lifecycle_warning_deprecated")
+  expect_s3_class(wrn, "lifecycle_warning_deprecated")
+  expect_snapshot(wrn)
+
+  # Calling it again gives no warning at all
+  wrn <- catch_cnd(retired(), classes = "lifecycle_warning_deprecated")
+  expect_null(wrn)
 
+  # With `"warning"` - warning shows unconditionally
   local_options(lifecycle_verbosity = "warning")
 
-  wrn <- catch_cnd(deprecate_warn(
-    "1.0.0",
-    "foo()",
-    id = "once-per-session-no-note"
-  ))
-  expect_false(grepl("once per session", conditionMessage(wrn)))
+  retired <- function() {
+    deprecate_warn("1.0.0", "foo()", id = "unconditional")
+  }
+
+  # First time doesn't show "once per session" message because we always warn
+  wrn <- catch_cnd(retired(), classes = "lifecycle_warning_deprecated")
+  expect_s3_class(wrn, "lifecycle_warning_deprecated")
+  expect_snapshot(wrn)
+
+  # Calling it again shows the warning again, again without "once per session"
+  wrn <- catch_cnd(retired(), classes = "lifecycle_warning_deprecated")
+  expect_s3_class(wrn, "lifecycle_warning_deprecated")
+  expect_snapshot(wrn)
 })
 
 test_that("the topenv of the empty env is not the global env", {