该技能用于按 tidyverse 惯例管理 R 包函数与参数的生命周期,核心依赖 lifecycle 包。
用途与主要能力:为函数或参数标注 experimental、deprecated、superseded 等生命周期阶段;执行弃用、更名与替代流程;为受影响函数编写弃用辅助工具。
必要用法:先检查 man/figures/ 下是否存在 lifecycle-*.svg 文件以判断是否已配置;若未配置,运行 usethis::use_lifecycle(),该命令会在 DESCRIPTION 的 Imports 中加入 lifecycle、在包文档文件中加入 @importFrom lifecycle deprecated,并把徽章 SVG 复制到 man/figures/。在 roxygen2 文档中用 @description 与 @param 插入 lifecycle::badge("experimental") 等徽章;仅标注阶段与包整体阶段不同的函数或参数。实现弃用通常添加徽章与说明,并在函数体首行调用 lifecycle::deprecate_warn(),例如 lifecycle::deprecate_warn("1.0.0", "old_fun()", "new_fun()")。函数更名时把实现移到新名称,旧名称调用新函数并发出弃用警告。参数弃用使用 deprecated() 作默认值并用 lifecycle::is_present() 检查,再用 deprecate_warn() 提示。替代函数用 superseded 徽章文档化更优方案即可,无需警告;实验性函数用 experimental 徽章并调用 lifecycle::signal_stage()。弃用三阶段函数为 deprecate_soft()(首次阶段,仅警告直接用户和测试期间)、deprecate_warn()(标准弃用,每 8 小时警告一次)、deprecate_stop()(移除前最后阶段,报错并给出提示)。
适用场景:R 包 API 演进、弃用与更名、批量参数弃用、生命周期文档与测试。可用 expect_snapshot() 测试弃用,或用 withr::local_options(lifecycle_verbosity = "quiet") 抑制警告。
限制:资料未提供其他限制与安装细节;具体阶段定义与转换可参考 references/lifecycle-stages.md。