x}G:wurjs12]"ioG^]IȢVQqof>`jt\gE5|a~ɒAc|Fr-cwg";'T`=%C-Q̟ID_I:V@c 6ac,7i+EGs) aÙ#3 $5fP[iSM1Μhr.3ʈ>jp gHKӪpxf!
F F,u E WuK(ލuU¢ >ɸ0sŨN|b ;o-Zzzp $xZ1 a_InY]8( TtV62eEfDp_r][˳ɴ,0̪s o('k-s}b^TZ`&<Zĥ<\7QWҌ4~sG"Y]nn ܩQv5u=?`FF }NBNҰ)}Q&G*J4":, [A6 f$eE ~qኄNM >K ΗãՉ|CSrISc#kw:-9`@GGJSiPy[?C
/y,AdI]790GT
_0>qP2+KĸHzP7ٲ %
u*ԙ5Q +cɢF]y [AX꿚7+|Dܻ Ech[0mxv'e.x2%
hP_c)̓u{g~nPs*@_ п][ eȘ rX]xgsbl4 w|-¼x97hK{ij,`k(@`s|2V\ˇsXB
q2^ ӟ,SA "Hy;`9,]вq[ D dsRرuD1.~KL b%yK*ҏyJ 5rmLPh^R:GFlbOpyX :'WC~9=C- 3A-{~W CݍҐxM81K@L:f'Y{pK/_1\p9o0
9B~PJiJ>{Ύ*gi] >#MȆ"s`hqNn8OMLdHT 7^ i]xԂ6ORiÙFes?́18Lc*.%NXZ}ͤ(Sbfc8I-
p
_jk8߬K˃zsvanf'ߦ,Q3Ok$wR*?Y/P[OĤ B$yU{o@yF}hzϘ~A8he㓎җ:+^(J,(fwH*32Y҆ ɮbzȿ-ǥR0=lg4k.7e1 z7:q l:(Nݏ ~ =4gi1gۻ U0ӈY
8Y?V}\҈ZDe:kbj7}f7zrI'_a8_EI0TTJRo
ڮf٢dt&/0k>I>ь蘡GӻδYq{=HΎnDUltȵ5 q<;}ƙeh1 2ǧ W>
8 6);(&_IFAw% 8N`h#P5n4O7/za+vƔU& zXKO"dSI=ӟ_yA E% Ԩ+;Nt0 /W)_C Y]`u YkB}y/YY9q۟gN?я@3MYKU!zqcY;,SɌh{g9F//qNjYH4/ rV X!~]09?Q;7Ltf? Bl`x[;[gxTXmttlrN37-' 3oew {{#
J `;ṿN@ `=O %GdB+i5~?ZZ .j(O| w,%0"8{exlc5>
֮ Ge%GLmكJ[M \#J^i`~Uk7VX]A{'W<4ϝPh; 'J<7_j89=#2.%
\P^8{9F2\,z4IZʒ/on9ϓ
>nqSzt3Z|?2$ 8-& YKq@h0YzR X 蚯x.0*q>x ! {x\r0 Ƃm rdZ]ZHڢ,`ڿ,`dxx0:5J~+/k!" *B\ NXR:Ӆ>M3
Use lifecycle to document the status of your exported functions and arguments: Choose one of the 7 lifecycle stages a function or argument can be in. You can choose from 4 development stages (experimental, maturing, stable, and questining) and 3 deprecation stages (soft-deprecated, deprecated, and defunct). If the function or argument is deprecated, make sure your users know about by calling Include the relevant lifecycle badge in your documentation. The lifecycle stages for functions and arguments closely mirror the lifecycle stages for packages. There are 4 development stages. Once the decision of discontinuing a feature has been made, it goes through 3 deprecation stages. Finally, when a feature is no longer exposed or mentioned in the released version of the package, it is said to be archived. Make sure your users know what stage a feature is by adding badges in the help topics of your functions. Call Use the This badge renders as text in non-HTML documentation. To document the status of a whole function, a good place to include the badge is at the top of the For functions in development, you typically don’t need to advertise the status if it is the same as the package as a whole. For instance, if your package is maturing, only signal functions in the experimental, stable, and questioning stages. lifecycle offers three levels of verbosity corresponding to the three deprecation stages. Soft deprecation: At this stage, call This function only warns (a) users who try the feature from the global workspace, and (b) developers who directly use the feature, when they run unit tests with testthat. No warning is issued outside of unit tests, or when the deprecated feature is called from another package then ther own. When a warning does get issued, users only see it once per session rather than at each invokation. Deprecation: At this stage, call Defunct: The feature is discontinued. Call These functions take the version number starting from which the feature is considered deprecated (it should remain the same across all deprecation stages), and a feature descriptor: You can optionally provide a replacement: For the purpose of these examples we explicitly mentioned the namespace with The syntax for deprecating argument is based on the syntax for deprecating functions: lifecycle also provides the Call Some manual search and replace is needed to bump the status of deprecated features. We recommend starting with defunct features and work your way up: Search for Search for Search for Call Don’t forget to update the badges in the documentation topics. Test whether your package depends on deprecated features directly or indirectly by setting the verbosity option in the This forces all deprecated features to fail. You can also set the relevant options manually to force warnings or errors in your session: Forcing warnings can be useful in conjuction with Test whether a deprecated feature still works by disabling the warnings with Test that a feature is correctly deprecated by forcing warnings and checking the class Defunct features throw errors of class 53jͼrX* fɊ:/ӛmQ晒ȟ7\?g >:ԭUa!U 6pxɧpwG-_ a _Ͷ>@x ^AU ju&rr!O7~ /ZeQC~ڸ C"((\\=HF21|vT fϝo*gFYjth #+\LysFݒ_6'NE;ȑ=3A XEQ"zy<_YhPɓ.`NGK7лGWY/k'ُ"Ӎ ;a0)NaqtY@lgХ{, b89/]!P}$uW,Wc?"ǪQ >vL GU1R_-v6@-].hbe߶c)Mj#%
^#qXׄ`#_}{cHE~5bޘmƢRr)Ku_ܓ6g# ufe MxD99hO#ڜ(lO:}ZޒwuqO+}q"ʑԴKY":K(
{\4ir'F tr@ ~(ykN "WE
This is a new feature that is in the very early stage of development. It is exported so users can start to use it and report feedback, but its interface and/or behaviour is likely to change in the future. It is generally best to avoid depending on experimental features.
1. 
The interface and behaviour of a maturing feature has been roughed out, but finer details are likely to change. It still needs more feedback to find the optimal API.
1. 
A feature is considered stable when the author is happy with its interface and behaviour. Major changes are unlikely, and breaking changes will occur gradually, through a deprecation process.
1. 
The author is no longer convinced that the feature is the optimal approach. However, there are no recommended alternatives yet.
Once the decision of discontinuing a feature has been made, it goes through 3 __deprecation__ stages.
1. 
The author is no longer happy with a feature because they consider it sub-optimal compared to some other approach, or simply because they no longer have the time to maintain it. A soft-deprecated feature can still be used without hassle, but users should consider switching to an alternative approach.
1. 
The feature is likely to be discontinued in the next major release. Users should switch to an alternative approach as soon as possible.
1. 
The feature can no longer be used. A defunct function is still exported, and a defunct argument is still part of the signature. This way an informative error can be thrown.
Finally, when a feature is no longer exposed or mentioned in the released version of the package, it is said to be __archived__.
### Badges {#rd-badges}
Make sure your users know what stage a feature is by adding badges in the help topics of your functions.
* Call `usethis::use_lifecycle()` to import the badges in your package.
* Use the `lifecycle` Rd macro to insert a badge:
```
#' \lifecycle{experimental}
#' \lifecycle{soft-deprecated}
```
This badge renders as text in non-HTML documentation. To document the status of a whole function, a good place to include the badge is at the top of the `@description` block. To document an argument, you can put the badge in the argument description.
* For functions in development, you typically don't need to advertise the status if it is the same as the package as a whole. For instance, if your package is [maturing](https://www.tidyverse.org/lifecycle/#maturing), only signal functions in the experimental, stable, and questioning stages.
### Verbosity of deprecation
lifecycle offers three levels of verbosity corresponding to the three deprecation stages.
* __Soft deprecation__: At this stage, call `deprecate_soft()` to start warning users about the deprecation in the least disruptive way.
This function only warns (a) users who try the feature from the global workspace, and (b) developers who directly use the feature, when they run unit tests with testthat. No warning is issued outside of unit tests, or when the deprecated feature is called from another package then ther own.
When a warning does get issued, users only see it once per session rather than at each invokation.
* __Deprecation__: At this stage, call `deprecate_warn()` to warn unconditionally about the deprecated feature. The warning is issued only once per session.
* __Defunct__: The feature is discontinued. Call `deprecate_stop()` to fail with an error.
### Deprecating functions
These functions take the version number starting from which the feature is considered deprecated (it should remain the same across all deprecation stages), and a feature descriptor:
```{r}
deprecate_warn("1.0.0", "mypkg::foo()")
```
You can optionally provide a replacement:
```{r}
deprecate_warn("1.0.0", "mypkg::foo()", "new()")
```
For the purpose of these examples we explicitly mentioned the namespace with `mypkg::`, however you can typically omit it because lifecycle infers the namespace from the calling environment. Specifying the namespace is mostly useful when the replacement is implemented in a different package.
```{r}
# The new replacement
foobar_adder <- function(foo, bar) {
foo + bar
}
# The old function still exported for compatibility
foobaz_adder <- function(foo, bar) {
deprecate_warn("1.0.0", "foobaz_adder()", "foobar_adder()")
foobar_adder(foo, bar)
}
```
### Deprecating arguments
The syntax for deprecating argument is based on the syntax for deprecating functions:
```{r}
deprecate_warn("1.0.0", "mypkg::foo(arg = )")
deprecate_warn("1.0.0", "mypkg::foo(arg = )", "mypkg::foo(new = )")
```
lifecycle also provides the `deprecated()` sentinel to use as default argument. This provides self-documentation for your users, and makes it possible for external tools to determine which arguments are deprecated. This sentinel is simply the missing argument, so you can test whether the argument was supplied with `rlang::is_missing()`:
```{r}
foobar_adder <- function(foo, bar, baz = deprecated()) {
# Check if user has supplied `baz` instead of `bar`
if (!rlang::is_missing(baz)) {
# Signal the deprecation to the user
deprecate_warn("1.0.0", "foobar_adder(baz = )", "foobar_adder(bar = )")
# Deal with the deprecated argument for compatibility
bar <- baz
}
foo + bar
}
```
### Workflow
#### Where do these deprecation warnings come from?
Call `lifecycle::last_warnings()` to see backtraces for all the deprecation warnings that were issued during the last top-level command.
#### Bumping deprecation stage
Some manual search and replace is needed to bump the status of deprecated features. We recommend starting with defunct features and work your way up:
1. Search for `deprecate_stop()` and remove the feature from the package. The feature is now archived.
1. Search for `deprecate_warn()` and replace with `deprecate_stop()`.
1. Search for `deprecate_soft()` and replace with `deprecate_warn()`.
1. Call `deprecate_soft()` from newly deprecated functions.
Don't forget to update the badges in the documentation topics.
#### Find out what deprecated features you rely on
Test whether your package depends on deprecated features directly or indirectly by setting the verbosity option in the `tests/testthat.R` file just before `test_check()` is called:
```{r, eval = FALSE}
library(testthat)
library(mypackage)
options(lifecycle_verbosity = "error")
test_check("mypackage")
```
This forces all deprecated features to fail. You can also set the relevant options manually to force warnings or errors in your session:
```{r, eval = FALSE}
# Force silence
options(lifecycle_verbosity = "quiet")
# Force warnings
options(lifecycle_verbosity = "warning")
# Force errors
options(lifecycle_verbosity = "error")
```
Forcing warnings can be useful in conjuction with `last_warnings()`, which prints backtraces for all the deprecation warnings issued during the last top-level command.
#### Test deprecated features
Test whether a deprecated feature still works by disabling the warnings with `scoped_lifecycle_silence()`:
```{r, eval = FALSE}
test_that("`baz` argument of `foobar_adder()` still works", {
withr::local_options(list(lifecycle_verbosity = "quiet"))
foobar_adder(1, baz = 2)
})
```
Test that a feature is correctly deprecated by forcing warnings and checking the class `"lifecycle_warning_deprecated"`:
```{r, eval = FALSE}
test_that("`baz` argument of `foobar_adder()` is deprecated", {
withr::local_options(list(lifecycle_verbosity = "warning"))
expect_warning(foobar_adder(1, baz = 2), class = "lifecycle_warning_deprecated")
})
```
Defunct features throw errors of class `"lifecycle_error_deprecated"`:
```{r, eval = FALSE}
test_that("`foo()` is defunct", {
expect_error(foo(), class = "lifecycle_error_deprecated")
})
```
lifecycle/R/ 0000755 0001762 0000144 00000000000 13516776053 012427 5 ustar ligges users lifecycle/R/lifecycle-package.R 0000644 0001762 0000144 00000001371 13516551340 016072 0 ustar ligges users #' @keywords internal
#' @import rlang
"_PACKAGE"
# The following block is used by usethis to automatically manage
# roxygen namespace tags. Modify with care!
## usethis namespace: start
## usethis namespace: end
NULL
# For R 3.2 support
strrep <- function(x, times) {
x <- as.character(x)
if (length(x) == 0L) {
return(x)
}
unlist(.mapply(function(x, times) {
if (is.na(x) || is.na(times)) {
return(NA_character_)
}
if (times <= 0L) {
return("")
}
paste0(replicate(times, x), collapse = "")
}, list(x = x, times = times), MoreArgs = list()), use.names = FALSE)
}
sexp_address <- NULL
.onLoad <- function(lib, pkg) {
# FIXME: Export from rlang
sexp_address <<- env_get(ns_env("rlang"), "sexp_address")
}
lifecycle/R/utils.R 0000644 0001762 0000144 00000002274 13514370224 013703 0 ustar ligges users
has_colour <- function() is_installed("crayon") && crayon::has_color()
silver <- function(x) if (has_colour()) crayon::silver(x) else x
upcase1 <- function(x) {
substr(x, 1, 1) <- toupper(substr(x, 1, 1))
x
}
cat_line <- function(...) {
cat(paste0(..., "\n", collapse = ""))
}
paste_line <- function(...) {
paste(chr(...), collapse = "\n")
}
has_crayon <- function() {
is_installed("crayon") && crayon::has_color()
}
red <- function(x) if (has_crayon()) crayon::red(x) else x
blue <- function(x) if (has_crayon()) crayon::blue(x) else x
green <- function(x) if (has_crayon()) crayon::green(x) else x
yellow <- function(x) if (has_crayon()) crayon::yellow(x) else x
magenta <- function(x) if (has_crayon()) crayon::magenta(x) else x
cyan <- function(x) if (has_crayon()) crayon::cyan(x) else x
blurred <- function(x) if (has_crayon()) crayon::blurred(x) else x
silver <- function(x) if (has_crayon()) crayon::silver(x) else x
bold <- function(x) if (has_crayon()) crayon::bold(x) else x
italic <- function(x) if (has_crayon()) crayon::italic(x) else x
underline <- function(x) if (has_crayon()) crayon::underline(x) else x
lifecycle/R/badge.R 0000644 0001762 0000144 00000005273 13516776032 013620 0 ustar ligges users #' Embed a lifecycle badge in documentation
#'
#' @description
#'
#' Call `usethis::use_lifecycle()` to import the badges in your
#' package. Then use the `lifecycle` Rd macro to insert a lifecycle
#' badges in your documentation, with the relevant lifecycle stage as
#' argument:
#'
#' ```
#' \lifecycle{experimental}
#' \lifecycle{soft-deprecated}
#' ```
#'
#' The badge is displayed as image in the HTML version of the
#' documentation and as text otherwise.
#'
#' If the deprecated feature is a function, a good place for this
#' badge is at the top of the topic description (if the deprecated
#' function is documented with other functions, it might be a good
#' idea to extract it in its own documentation topic to prevent
#' confusion). If it is an argument, you can put the badge in the
#' argument description.
#'
#' @section Badges:
#' * \verb{\lifecycle{experimental}}: \lifecycle{experimental}
#' * \verb{\lifecycle{maturing}}: \lifecycle{maturing}
#' * \verb{\lifecycle{stable}}: \lifecycle{stable}
#' * \verb{\lifecycle{questioning}}: \lifecycle{questioning}
#' * \verb{\lifecycle{archived}}: \lifecycle{archived}
#' * \verb{\lifecycle{soft-deprecated}}: \lifecycle{soft-deprecated}
#' * \verb{\lifecycle{deprecated}}: \lifecycle{deprecated}
#' * \verb{\lifecycle{defunct}}: \lifecycle{defunct}
#'
#' @details
#'
#' The `lifecycle{}` macro is made available by adding this field to
#' DESCRIPTION (this is done automatically by
#' `usethis::use_lifecycle()`):
#'
#' ```
#' RdMacros: lifecycle
#' ```
#'
#' The macro expands to this expression:
#'
#' ```
#' \Sexpr[results=rd, stage=render]{lifecycle::badge("experimental")}
#' ```
#'
#' @param stage A lifecycle stage as a string, one of:
#' `"experimental"`, `"maturing"`, `"stable"`, `"questioning"`,
#' `"archived"`, `"soft-deprecated"`, `"deprecated"`, `"defunct"`.
#' @return An `Rd` expression describing the lifecycle stage.
#'
#' @export
badge <- function(stage) {
url <- paste0("https://www.tidyverse.org/lifecycle/#", stage)
img <- lifecycle_img(stage, url)
sprintf("\\ifelse{html}{%s}{\\strong{%s}}", img, upcase1(stage))
}
lifecycle_img <- function(stage, url) {
file <- sprintf("lifecycle-%s.svg", stage)
stage_alt <- upcase1(stage)
switch(stage,
experimental = ,
maturing = ,
stable = ,
questioning = ,
retired = ,
archived =
sprintf(
"\\out{}",
url,
file.path("figures", file),
stage_alt
)
,
`soft-deprecated` = ,
deprecated = ,
defunct =
sprintf(
"\\figure{%s}{options: alt='%s lifecycle'}",
file,
stage_alt
),
abort(sprintf("Unknown lifecycle stage `%s`", stage))
)
}
lifecycle/R/signal.R 0000644 0001762 0000144 00000023532 13516776053 014034 0 ustar ligges users #' Deprecate functions and arguments
#'
#' @description
#'
#' These functions provide three levels of verbosity for deprecated
#' functions.
#'
#' * `deprecate_soft()` warns only if the deprecated function is
#' called from the global environment (so the user can change their
#' script) or from the package currently being tested (so the
#' package developer can fix the package). Use for soft-deprecated
#' functions.
#'
#' * `deprecate_warn()` warns unconditionally. Use for deprecated functions.
#'
#' * `deprecate_stop()` fails unconditionally. Use for defunct functions.
#'
#' Warnings are only issued once per session to avoid overwhelming the
#' user. See the [verbosity option][verbosity] to control this
#' behaviour.
#'
#' @param when The package version when function/argument was deprecated.
#' @param what If the deprecated feature is a whole function, the
#' function name: `"foo()"`. If it's an argument that is being
#' deprecated, the function call should include the argument:
#' `"foo(arg = )"`.
#'
#' You can optionally supply the namespace: `"ns::foo()"`. If not
#' supplied, it is inferred from the caller environment.
#' @param with An optional replacement for the deprecated feature.
#' This should be a string of the same form as `what`.
#' @param details The deprecation message is generated from `when`,
#' `what`, and `with`. You can additionally supply a string
#' `details` to be appended to the message.
#' @param id The id of the deprecation. A warning is issued only once
#' for each `id`. Defaults to the generated message, but you should
#' give a unique ID when the message in `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.
#' @param env The environment in which the deprecated function
#' was called. A warning is issued if called from the global
#' environment. If testthat is running, a warning is also called if
#' the deprecated function was called from the package being tested.
#'
#' This typically doesn't need to be specified, unless you call
#' `deprecate_soft()` or `deprecate_warn()` from an internal helper.
#' In that case, you need to forward the calling environment.
#' @return `NULL`, invisibly.
#'
#' @seealso [lifecycle()]
#'
#' @examples
#' # A deprecated function `foo`:
#' deprecate_warn("1.0.0", "foo()")
#'
#' # A deprecated argument `arg`:
#' deprecate_warn("1.0.0", "foo(arg = )")
#'
#' # A deprecated function with a function replacement:
#' deprecate_warn("1.0.0", "foo()", "bar()")
#'
#' # A deprecated function with a function replacement from a
#' # different package:
#' deprecate_warn("1.0.0", "foo()", "otherpackage::bar()")
#'
#' # A deprecated function with an argument replacement:
#' deprecate_warn("1.0.0", "foo()", "foo(bar = )")
#'
#' @export
deprecate_soft <- function(when,
what,
with = NULL,
details = NULL,
id = NULL,
env = caller_env(2)) {
verbosity <- lifecycle_verbosity()
if (verbosity == "quiet") {
return(invisible(NULL))
}
if (verbosity %in% c("warning", "error") || env_inherits_global(env)) {
deprecate_warn(when, what, with = with, details = details, id = id)
return(invisible(NULL))
}
if (from_testthat(env)) {
# Warn repeatedly in unit tests
scoped_options(lifecycle_verbosity = "warning")
deprecate_warn(when, what, with = with, details = details, id = id)
return(invisible(NULL))
}
msg <- lifecycle_build_message(when, what, with, details, "deprecate_warn")
signal(msg, "lifecycle_soft_deprecated")
}
# TRUE if we are in unit tests and the package being tested is the
# same as the package that called
from_testthat <- function(env) {
tested_package <- Sys.getenv("TESTTHAT_PKG")
# Test for environment names rather than reference/contents because
# testthat clones the namespace
nzchar(tested_package) &&
identical(Sys.getenv("NOT_CRAN"), "true") &&
env_name(topenv(env)) == env_name(ns_env(tested_package))
}
#' @rdname deprecate_soft
#' @export
deprecate_warn <- function(when,
what,
with = NULL,
details = NULL,
id = NULL,
env = caller_env(2)) {
msg <- lifecycle_build_message(when, what, with, details, "deprecate_warn")
verbosity <- lifecycle_verbosity()
id <- id %||% msg
stopifnot(is_string(id))
if (verbosity == "quiet") {
return(invisible(NULL))
}
if (verbosity == "default" && env_has(deprecation_env, id) && !from_testthat(env)) {
return(invisible(NULL))
}
env_poke(deprecation_env, id, TRUE);
if (verbosity == "error") {
deprecate_stop(when, what, with = with, details = details)
} else {
if (verbosity == "default") {
msg <- paste_line(
msg,
silver("This warning is displayed once per session."),
silver("Call `lifecycle::last_warnings()` to see where this warning was generated.")
)
}
trace <- trace_back(bottom = caller_env())
wrn <- new_deprecated_warning(msg, trace)
# Record muffled warnings if testthat is running because it
# muffles all warnings but we still want to examine them after a
# run of `devtools::test()`
maybe_push_warning <- function() {
if (Sys.getenv("TESTTHAT_PKG") != "") {
push_warning(wrn)
}
}
withRestarts(muffleWarning = maybe_push_warning, {
signalCondition(wrn)
push_warning(wrn)
warning(wrn)
})
}
}
#' @rdname deprecate_soft
#' @export
deprecate_stop <- function(when,
what,
with = NULL,
details = NULL) {
msg <- lifecycle_build_message(when, what, with, details, "deprecate_stop")
stop(cnd(
c("lifecycle_error_deprecated", "defunctError", "error", "condition"),
old = NULL,
new = NULL,
package = NULL,
message = msg
))
}
env_inherits_global <- function(env) {
# `topenv(emptyenv())` returns the global env. Return `FALSE` in
# that case to allow passing the empty env when the
# soft-deprecation should not be promoted to deprecation based on
# the caller environment.
if (is_reference(env, empty_env())) {
return(FALSE)
}
is_reference(topenv(env), global_env())
}
lifecycle_validate_message <- function(msg) {
stopifnot(is_character(msg))
paste0(msg, collapse = "\n")
}
lifecycle_build_message <- function(when,
what,
with = NULL,
details = chr(),
signaller) {
details <- details %||% chr()
stopifnot(
is_string(when),
is_string(what),
is_null(with) || is_string(with),
is_character(details)
)
what <- signal_validate_what(what, "what", signaller)
fn <- signal_validate_fn(what$call)
arg <- signal_validate_arg(what$call, signaller)
if (is_null(what$pkg)) {
env <- topenv(caller_env(2))
pkg <- signal_validate_pkg(env)
} else {
pkg <- what$pkg
}
if (is_null(arg)) {
msg <- glue::glue("`{ fn }()` is deprecated as of { pkg } { when }.")
} else {
msg <- glue::glue("The `{ arg }` argument of `{ fn }()` is deprecated as of { pkg } { when }.")
}
if (!is_null(with)) {
with <- signal_validate_what(with, "with", signaller)
with_fn <- signal_validate_fn(with$call)
with_arg <- signal_validate_arg(with$call, signaller)
with_pkg <- with$pkg %||% pkg
if (!is_null(with_pkg) && pkg != with_pkg) {
with_fn <- glue::glue("{ with_pkg }::{ with_fn }")
}
if (is_null(with_arg)) {
please <- glue::glue("Please use `{ with_fn }()` instead.")
} else if (fn == with_fn) {
please <- glue::glue("Please use the `{ with_arg }` argument instead.")
} else {
please <- glue::glue("Please use the `{ with_arg }` argument of `{ with_fn }()` instead.")
}
msg <- paste0(msg, "\n", please)
}
paste_line(msg, details)
}
signal_validate_what <- function(what, arg, signaller) {
call <- parse_expr(what)
if (!is_call(call)) {
abort(glue::glue(
"
Internal error: `what` must have function call syntax.
# Good:
{ signaller }({ what } = \"myfunction()\")
# Bad:
{ signaller }({ what } = \"myfunction\")
"
))
}
head <- node_car(call)
if (is_call(head, "::")) {
pkg <- as_string(node_cadr(head))
call[[1]] <- node_cadr(node_cdr(head))
} else {
pkg <- NULL
}
list(pkg = pkg, call = call)
}
signal_validate_fn <- function(call) {
fn <- node_car(call)
if (!is_symbol(fn)) {
abort("Internal error: `what` must refer to a function name.")
}
# Deparse so non-syntactic names are backticked
expr_deparse(fn)
}
signal_validate_arg <- function(call, signaller) {
arg <- node_cdr(call)
if (is_null(arg)) {
return(NULL)
}
if (length(arg) != 1L) {
abort("Internal error: `what` can't refer to more than one argument.")
}
if (is_null(node_tag(arg)) || !is_missing(node_car(arg))) {
abort(glue::glue(
"
Internal error: `what` must refer to arguments in the LHS of `=`.
# Good:
{ signaller }(what = \"myfunction(arg = )\")
# Bad:
{ signaller }(what = \"myfunction(arg)\")
"
))
}
as_string(node_tag(arg))
}
signal_validate_pkg <- function(env) {
if (is_reference(env, global_env())) {
# Convenient for experimenting interactively
return("
This is a new feature that is in the very early stage of development. It is exported so users can start to use it and report feedback, but its interface and/or behaviour is likely to change in the future. It is generally best to avoid depending on experimental features.
1. The interface and behaviour of a maturing feature has been roughed out, but finer details are likely to change. It still needs more feedback to find the optimal API.
1. A feature is considered stable when the author is happy with its interface and behaviour. Major changes are unlikely, and breaking changes will occur gradually, through a deprecation process.
1. The author is no longer convinced that the feature is the optimal approach. However, there are no recommended alternatives yet.
Once the decision of discontinuing a feature has been made, it goes through 3 __deprecation__ stages.
1. The author is no longer happy with a feature because they consider it sub-optimal compared to some other approach, or simply because they no longer have the time to maintain it. A soft-deprecated feature can still be used without hassle, but users should consider switching to an alternative approach.
1. The feature is likely to be discontinued in the next major release. Users should switch to an alternative approach as soon as possible.
1. The feature can no longer be used. A defunct function is still exported, and a defunct argument is still part of the signature. This way an informative error can be thrown.
Finally, when a feature is no longer exposed or mentioned in the released version of the package, it is said to be __archived__.
### Badges {#rd-badges}
Make sure your users know what stage a feature is by adding badges in the help topics of your functions.
* Call `usethis::use_lifecycle()` to import the badges in your package.
* Use the `lifecycle` Rd macro to insert a badge:
```
#' \lifecycle{experimental}
#' \lifecycle{soft-deprecated}
```
This badge renders as text in non-HTML documentation. To document the status of a whole function, a good place to include the badge is at the top of the `@description` block. To document an argument, you can put the badge in the argument description.
* For functions in development, you typically don't need to advertise the status if it is the same as the package as a whole. For instance, if your package is [maturing](https://www.tidyverse.org/lifecycle/#maturing), only signal functions in the experimental, stable, and questioning stages.
### Verbosity of deprecation
lifecycle offers three levels of verbosity corresponding to the three deprecation stages.
* __Soft deprecation__: At this stage, call `deprecate_soft()` to start warning users about the deprecation in the least disruptive way.
This function only warns (a) users who try the feature from the global workspace, and (b) developers who directly use the feature, when they run unit tests with testthat. No warning is issued outside of unit tests, or when the deprecated feature is called from another package then ther own.
When a warning does get issued, users only see it once per session rather than at each invokation.
* __Deprecation__: At this stage, call `deprecate_warn()` to warn unconditionally about the deprecated feature. The warning is issued only once per session.
* __Defunct__: The feature is discontinued. Call `deprecate_stop()` to fail with an error.
### Deprecating functions
These functions take the version number starting from which the feature is considered deprecated (it should remain the same across all deprecation stages), and a feature descriptor:
```{r}
deprecate_warn("1.0.0", "mypkg::foo()")
```
You can optionally provide a replacement:
```{r}
deprecate_warn("1.0.0", "mypkg::foo()", "new()")
```
For the purpose of these examples we explicitly mentioned the namespace with `mypkg::`, however you can typically omit it because lifecycle infers the namespace from the calling environment. Specifying the namespace is mostly useful when the replacement is implemented in a different package.
```{r}
# The new replacement
foobar_adder <- function(foo, bar) {
foo + bar
}
# The old function still exported for compatibility
foobaz_adder <- function(foo, bar) {
deprecate_warn("1.0.0", "foobaz_adder()", "foobar_adder()")
foobar_adder(foo, bar)
}
```
### Deprecating arguments
The syntax for deprecating argument is based on the syntax for deprecating functions:
```{r}
deprecate_warn("1.0.0", "mypkg::foo(arg = )")
deprecate_warn("1.0.0", "mypkg::foo(arg = )", "mypkg::foo(new = )")
```
lifecycle also provides the `deprecated()` sentinel to use as default argument. This provides self-documentation for your users, and makes it possible for external tools to determine which arguments are deprecated. This sentinel is simply the missing argument, so you can test whether the argument was supplied with `rlang::is_missing()`:
```{r}
foobar_adder <- function(foo, bar, baz = deprecated()) {
# Check if user has supplied `baz` instead of `bar`
if (!rlang::is_missing(baz)) {
# Signal the deprecation to the user
deprecate_warn("1.0.0", "foobar_adder(baz = )", "foobar_adder(bar = )")
# Deal with the deprecated argument for compatibility
bar <- baz
}
foo + bar
}
```
### Workflow
#### Where do these deprecation warnings come from?
Call `lifecycle::last_warnings()` to see backtraces for all the deprecation warnings that were issued during the last top-level command.
#### Bumping deprecation stage
Some manual search and replace is needed to bump the status of deprecated features. We recommend starting with defunct features and work your way up:
1. Search for `deprecate_stop()` and remove the feature from the package. The feature is now archived.
1. Search for `deprecate_warn()` and replace with `deprecate_stop()`.
1. Search for `deprecate_soft()` and replace with `deprecate_warn()`.
1. Call `deprecate_soft()` from newly deprecated functions.
Don't forget to update the badges in the documentation topics.
#### Find out what deprecated features you rely on
Test whether your package depends on deprecated features directly or indirectly by setting the verbosity option in the `tests/testthat.R` file just before `test_check()` is called:
```{r, eval = FALSE}
library(testthat)
library(mypackage)
options(lifecycle_verbosity = "error")
test_check("mypackage")
```
This forces all deprecated features to fail. You can also set the relevant options manually to force warnings or errors in your session:
```{r, eval = FALSE}
# Force silence
options(lifecycle_verbosity = "quiet")
# Force warnings
options(lifecycle_verbosity = "warning")
# Force errors
options(lifecycle_verbosity = "error")
```
Forcing warnings can be useful in conjuction with `last_warnings()`, which prints backtraces for all the deprecation warnings issued during the last top-level command.
#### Test deprecated features
Test whether a deprecated feature still works by disabling the warnings with `scoped_lifecycle_silence()`:
```{r, eval = FALSE}
test_that("`baz` argument of `foobar_adder()` still works", {
withr::local_options(list(lifecycle_verbosity = "quiet"))
foobar_adder(1, baz = 2)
})
```
Test that a feature is correctly deprecated by forcing warnings and checking the class `"lifecycle_warning_deprecated"`:
```{r, eval = FALSE}
test_that("`baz` argument of `foobar_adder()` is deprecated", {
withr::local_options(list(lifecycle_verbosity = "warning"))
expect_warning(foobar_adder(1, baz = 2), class = "lifecycle_warning_deprecated")
})
```
Defunct features throw errors of class `"lifecycle_error_deprecated"`:
```{r, eval = FALSE}
test_that("`foo()` is defunct", {
expect_error(foo(), class = "lifecycle_error_deprecated")
})
```
lifecycle/inst/doc/lifecycle.html 0000644 0001762 0000144 00000150217 13516776442 016605 0 ustar ligges users
Usage of the lifecycle package
deprecate_soft(), deprecate_warn(), or deprecate_stop(). These functions try to be informative without being too verbose, with increasing levels of verbosity as the deprecation stage advances.Stages
This is a new feature that is in the very early stage of development. It is exported so users can start to use it and report feedback, but its interface and/or behaviour is likely to change in the future. It is generally best to avoid depending on experimental features.
The interface and behaviour of a maturing feature has been roughed out, but finer details are likely to change. It still needs more feedback to find the optimal API.
A feature is considered stable when the author is happy with its interface and behaviour. Major changes are unlikely, and breaking changes will occur gradually, through a deprecation process.
The author is no longer convinced that the feature is the optimal approach. However, there are no recommended alternatives yet.
The author is no longer happy with a feature because they consider it sub-optimal compared to some other approach, or simply because they no longer have the time to maintain it. A soft-deprecated feature can still be used without hassle, but users should consider switching to an alternative approach.
The feature is likely to be discontinued in the next major release. Users should switch to an alternative approach as soon as possible.
The feature can no longer be used. A defunct function is still exported, and a defunct argument is still part of the signature. This way an informative error can be thrown.Badges
usethis::use_lifecycle() to import the badges in your package.lifecycle Rd macro to insert a badge:#' \lifecycle{experimental}
#' \lifecycle{soft-deprecated}@description block. To document an argument, you can put the badge in the argument description.Verbosity of deprecation
deprecate_soft() to start warning users about the deprecation in the least disruptive way.deprecate_warn() to warn unconditionally about the deprecated feature. The warning is issued only once per session.deprecate_stop() to fail with an error.Deprecating functions
deprecate_warn("1.0.0", "mypkg::foo()")
#> Warning: `foo()` is deprecated as of mypkg 1.0.0.
#> This warning is displayed once per session.
#> Call `lifecycle::last_warnings()` to see where this warning was generated.deprecate_warn("1.0.0", "mypkg::foo()", "new()")
#> Warning: `foo()` is deprecated as of mypkg 1.0.0.
#> Please use `new()` instead.
#> This warning is displayed once per session.
#> Call `lifecycle::last_warnings()` to see where this warning was generated.mypkg::, however you can typically omit it because lifecycle infers the namespace from the calling environment. Specifying the namespace is mostly useful when the replacement is implemented in a different package.Deprecating arguments
deprecate_warn("1.0.0", "mypkg::foo(arg = )")
#> Warning: The `arg` argument of `foo()` is deprecated as of mypkg 1.0.0.
#> This warning is displayed once per session.
#> Call `lifecycle::last_warnings()` to see where this warning was generated.
deprecate_warn("1.0.0", "mypkg::foo(arg = )", "mypkg::foo(new = )")
#> Warning: The `arg` argument of `foo()` is deprecated as of mypkg 1.0.0.
#> Please use the `new` argument instead.
#> This warning is displayed once per session.
#> Call `lifecycle::last_warnings()` to see where this warning was generated.deprecated() sentinel to use as default argument. This provides self-documentation for your users, and makes it possible for external tools to determine which arguments are deprecated. This sentinel is simply the missing argument, so you can test whether the argument was supplied with rlang::is_missing():foobar_adder <- function(foo, bar, baz = deprecated()) {
# Check if user has supplied `baz` instead of `bar`
if (!rlang::is_missing(baz)) {
# Signal the deprecation to the user
deprecate_warn("1.0.0", "foobar_adder(baz = )", "foobar_adder(bar = )")
# Deal with the deprecated argument for compatibility
bar <- baz
}
foo + bar
}Workflow
Where do these deprecation warnings come from?
lifecycle::last_warnings() to see backtraces for all the deprecation warnings that were issued during the last top-level command.Bumping deprecation stage
deprecate_stop() and remove the feature from the package. The feature is now archived.deprecate_warn() and replace with deprecate_stop().deprecate_soft() and replace with deprecate_warn().deprecate_soft() from newly deprecated functions.Find out what deprecated features you rely on
tests/testthat.R file just before test_check() is called:# Force silence
options(lifecycle_verbosity = "quiet")
# Force warnings
options(lifecycle_verbosity = "warning")
# Force errors
options(lifecycle_verbosity = "error")last_warnings(), which prints backtraces for all the deprecation warnings issued during the last top-level command.Test deprecated features
scoped_lifecycle_silence():test_that("`baz` argument of `foobar_adder()` still works", {
withr::local_options(list(lifecycle_verbosity = "quiet"))
foobar_adder(1, baz = 2)
})"lifecycle_warning_deprecated":test_that("`baz` argument of `foobar_adder()` is deprecated", {
withr::local_options(list(lifecycle_verbosity = "warning"))
expect_warning(foobar_adder(1, baz = 2), class = "lifecycle_warning_deprecated")
})"lifecycle_error_deprecated":