Bring back fast signal_stage()

NAMESPACE

@@ -1,6 +1,5 @@
 # Generated by roxygen2: do not edit by hand
 
-S3method(conditionMessage,lifecycle_stage)
 S3method(print,lifecycle_warnings)
 export(badge)
 export(deprecate_soft)

NEWS.md

@@ -1,6 +1,6 @@
 # lifecycle (development version)
 
-* `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.
+* `signal_stage()` no longer does anything, and is now purely a way to express intent at the call site of whether a function is superseded or experimental (#203).
 
 * `deprecate_soft()` and `deprecate_warn()` are faster thanks to some internal refactoring (#191, #194, #195, #201).
 

R/signal.R

@@ -0,0 +1,64 @@
+#' Signal other experimental or superseded features
+#'
+#' @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, it is currently purely a way to
+#' express intent at the call site. In the future, we hope to replace this with
+#' a standardized call to `base::declare()`.
+#'
+#' @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 `r badge("deprecated")`
+#'
+#' @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 = deprecated()) {
+  # Does nothing
+  invisible()
+}
+
+#' Deprecated functions for signalling lifecycle stages
+#'
+#' @description
+#' `r badge("deprecated")`
+#' @name deprecated-signallers
+#' @keywords internal
+NULL
+
+#' @rdname deprecated-signallers
+#' @export
+signal_experimental <- function(when, what, env = caller_env()) {
+  deprecate_soft(
+    "1.1.0",
+    what = "signal_experimental()",
+    with = "signal_stage()",
+    id = "lifecycle_signal_experimental"
+  )
+  signal_stage("experimental", what)
+}
+
+#' @rdname deprecated-signallers
+#' @export
+signal_superseded <- function(when, what, env = caller_env()) {
+  deprecate_soft(
+    "1.1.0",
+    what = "signal_superseded()",
+    with = "signal_stage()",
+    id = "lifecycle_signal_superseded"
+  )
+  signal_stage("superseded", what)
+}

tests/testthat/_snaps/signal.md

@@ -0,0 +1,18 @@
+# `signal_experimental()` and `signal_superseded()` are deprecated
+
+    Code
+      signal_experimental("1.1.0", "foo()")
+    Condition
+      Warning:
+      `signal_experimental()` was deprecated in lifecycle 1.1.0.
+      i Please use `signal_stage()` instead.
+
+---
+
+    Code
+      signal_superseded("1.1.0", "foo()")
+    Condition
+      Warning:
+      `signal_superseded()` was deprecated in lifecycle 1.1.0.
+      i Please use `signal_stage()` instead.
+

tests/testthat/test-signal.R

@@ -0,0 +1,12 @@
+test_that("`signal_stage()` does nothing", {
+  expect_null(signal_stage("experimental", "pkg::foo(bar = 'baz')"), NULL)
+})
+
+test_that("`signal_experimental()` and `signal_superseded()` are deprecated", {
+  expect_snapshot({
+    signal_experimental("1.1.0", "foo()")
+  })
+  expect_snapshot({
+    signal_superseded("1.1.0", "foo()")
+  })
+})