{"slug":"lifecycle","title":"lifecycle","summary":"Guidance for managing R package lifecycle according to tidyverse principles using the lifecycle package. Use when: (1) Setting up lifecycle infrastructure in a package, (2) Deprecating functions or arguments, (3) Renaming functions or arguments, (4) Superseding functions, (5) Mar","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-08-28T19:34:15.976615Z","repo":{"url":"https://github.com/posit-dev/skills","stars":518,"forks":53,"license":"MIT","updatedAt":"2026-09-18T19:30:01Z"},"bodyHtml":"
\n

name: lifecycle\ndescription: \"Guidance for managing R package lifecycle according to tidyverse principles using the lifecycle package. Use when: (1) Setting up lifecycle infrastructure in a package, (2) Deprecating functions or arguments, (3) Renaming functions or arguments, (4) Superseding functions, (5) Marking functions as experimental, (6) Understanding lifecycle stages (stable, experimental, deprecated, superseded), or (7) Writing deprecation helpers for complex scenarios.\"\nmetadata:\nauthor: Garrick Aden-Buie (@gadenbuie)\nversion: \"1.1\"\nlicense: MIT

\n

R Package Lifecycle Management

\n

Manage function and argument lifecycle using tidyverse conventions and the lifecycle package.

\n

Setup

\n

Check if lifecycle is configured by looking for lifecycle-*.svg files in man/figures/.

\n

If not configured, run:

\n
usethis::use_lifecycle()\n
\n

This:

\n\n

Lifecycle Badges

\n

Insert badges in roxygen2 documentation:

\n
#' @description\n#' `r lifecycle::badge(\"experimental\")`\n#' `r lifecycle::badge(\"deprecated\")`\n#' `r lifecycle::badge(\"superseded\")`\n
\n

For arguments:

\n
#' @param old_arg `r lifecycle::badge(\"deprecated\")` Use `new_arg` instead.\n
\n

Only badge functions/arguments whose stage differs from the package's overall stage.

\n

Deprecating a Function

\n
    \n
  1. Add badge and explanation to @description:
    2. \n
\n
#' Do something\n#'\n#' @description\n#' `r lifecycle::badge(\"deprecated\")`\n#'\n#' `old_fun()` was deprecated in mypkg 1.0.0. Use [new_fun()] instead.\n#' @keywords internal\n
\n
    \n
  1. Add deprecate_warn() as first line of function body:
    2. \n
\n
old_fun <- function(x) {\n\nlifecycle::deprecate_warn(\"1.0.0\", \"old_fun()\", \"new_fun()\")\nnew_fun(x)\n}\n
\n
    \n
  1. Show migration in examples:
    2. \n
\n
#' @examples\n#' old_fun(x)\n#' # ->\n#' new_fun(x)\n
\n

Deprecation Functions

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FunctionWhen to Use
deprecate_soft()First stage; warns only direct users and during tests
deprecate_warn()Standard deprecation; warns once per 8 hours
deprecate_stop()Final stage before removal; errors with helpful message
\n

Deprecation workflow for major releases:

\n
    \n
  1. Search deprecate_stop() - consider removing function entirely
    2. \n
  2. Replace deprecate_warn() with deprecate_stop()
    3. \n
  3. Replace deprecate_soft() with deprecate_warn()
    4. \n
\n

Renaming a Function

\n

Move implementation to new name, call from old name with deprecation:

\n
#' @description\n#' `r lifecycle::badge(\"deprecated\")`\n#'\n#' `add_two()` was renamed to `number_add()` for API consistency.\n#' @keywords internal\n#' @export\nadd_two <- function(x, y) {\nlifecycle::deprecate_warn(\"1.0.0\", \"add_two()\", \"number_add()\")\nnumber_add(x, y)\n}\n\n#' Add two numbers\n#' @export\nnumber_add <- function(x, y) {\nx + y\n}\n
\n

Deprecating an Argument

\n

Use deprecated() as default value with is_present() check:

\n
#' @param path `r lifecycle::badge(\"deprecated\")` Use `file` instead.\nwrite_file <- function(x, file, path = deprecated()) {\n  if (lifecycle::is_present(path)) {\n    lifecycle::deprecate_warn(\"1.4.0\", \"write_file(path)\", \"write_file(file)\")\n    file <- path\n  }\n  # ... rest of function\n}\n
\n

Renaming an Argument

\n
add_two <- function(x, y, na_rm = TRUE, na.rm = deprecated()) {\n  if (lifecycle::is_present(na.rm)) {\n    lifecycle::deprecate_warn(\"1.0.0\", \"add_two(na.rm)\", \"add_two(na_rm)\")\n    na_rm <- na.rm\n  }\n  sum(x, y, na.rm = na_rm)\n}\n
\n

Superseding a Function

\n

For functions with better alternatives that shouldn't be removed:

\n
#' Gather columns into key-value pairs\n#'\n#' @description\n#' `r lifecycle::badge(\"superseded\")`\n#'\n#' Development on `gather()` is complete. For new code, use [pivot_longer()].\n#'\n#' `df %>% gather(\"key\", \"value\", x, y, z)` is equivalent to\n#' `df %>% pivot_longer(c(x, y, z), names_to = \"key\", values_to = \"value\")`.\n
\n

No warning needed - just document the preferred alternative.

\n

Marking as Experimental

\n
#' @description\n#' `r lifecycle::badge(\"experimental\")`\ncool_function <- function() {\n  lifecycle::signal_stage(\"experimental\", \"cool_function()\")\n  # ...\n}\n
\n

Testing Deprecations

\n

Test that deprecated functions work and warn appropriately:

\n
test_that(\"old_fun is deprecated\", {\n  expect_snapshot({\n    x <- old_fun(1)\n    expect_equal(x, expected_value)\n  })\n})\n
\n

Suppress warnings in existing tests:

\n
test_that(\"old_fun returns correct value\", {\n  withr::local_options(lifecycle_verbosity = \"quiet\")\n  expect_equal(old_fun(1), expected_value)\n})\n
\n

Deprecation Helpers

\n

For deprecations affecting many functions (e.g., removing a common argument), create an internal helper:

\n
warn_for_verbose <- function(\n  verbose = TRUE,\n  env = rlang::caller_env(),\n  user_env = rlang::caller_env(2)\n) {\n  if (!lifecycle::is_present(verbose) || isTRUE(verbose)) {\n    return(invisible())\n  }\n\n  lifecycle::deprecate_warn(\n    when = \"2.0.0\",\n    what = I(\"The `verbose` argument\"),\n    details = c(\n      \"Set `options(mypkg_quiet = TRUE)` to suppress messages.\",\n      \"The `verbose` argument will be removed in a future release.\"\n    ),\n    user_env = user_env\n  )\n\n  invisible()\n}\n
\n

Then use in affected functions:

\n
my_function <- function(..., verbose = deprecated()) {\n  warn_for_verbose(verbose)\n  # ...\n}\n
\n

Custom Deprecation Messages

\n

For non-standard deprecations, use I() to wrap custom text:

\n
lifecycle::deprecate_warn(\n  when = \"1.0.0\",\n  what = I('Setting option \"pkg.opt\" to \"foo\"'),\n  with = I('\"pkg.new_opt\"')\n)\n
\n

The what fragment must work with \"was deprecated in...\" appended.

\n

Reference

\n

See references/lifecycle-stages.md for detailed stage definitions and transitions.

\n","files":[{"path":"references/lifecycle-stages.md","sizeBytes":2238,"isText":true},{"path":"SKILL.md","sizeBytes":5948,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-08-28T19:34:39.184075Z","sha256":"9651FCDB232B1C765F34D44F22ECE1CC540CB8C99EF6FD6D2A8B90BA5D0C354B","sizeBytes":3555},"review":null,"source":{"repositoryUrl":"https://github.com/posit-dev/skills","path":"r-lib/lifecycle","license":"MIT","commit":"1bb49b8eecba38f04d39c2e6ddb8f8871382fe72","subtreeSha":"63E17C653150B3EB5A22E0F99A3D03A685A6EFBC84FE58826C02A89B6996EDA2","lastSyncedAt":"2026-09-21T13:51:07.177786Z"},"reviewedAt":"2026-08-28T19:35:41.625824Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/posit-dev/skills/tree/main/r-lib/lifecycle"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install posit-dev-skills@llmmart"},{"target":"git","command":"git clone https://github.com/posit-dev/skills.git"}]}