在维护 R 包 API 时：按…

适用于使用 roxygen2 和 lifecycle 包管理 R 包函数/参数生命周期（弃用、重命名、替代、实验性标记）的场景。

适用场景

解决思路

1. 检查 lifecycle 是否已配置：查看 man/figures/ 下是否存在 lifecycle-*.svg 文件。
2. 若未配置，运行 usethis::use_lifecycle()；它会把 lifecycle 加入 DESCRIPTION 的 Imports，把 @importFrom lifecycle deprecated 加入包文档文件，并复制 badge SVGs 到 man/figures/。
3. 在 roxygen2 的 @description 中插入生命周期 badge：`r lifecycle::badge("experimental")`、`r lifecycle::badge("deprecated")`、`r lifecycle::badge("superseded")`。
4. 对参数使用 badge：@param old_arg `r lifecycle::badge("deprecated")` Use `new_arg` instead.。
5. 仅对生命周期阶段与包整体阶段不同的函数/参数加 badge。
6. 弃用函数第 1 步：在 @description 中加 deprecated badge 和解释，例如 `old_fun()` was deprecated in mypkg 1.0.0. Use [new_fun()] instead.，并加 @keywords internal。
7. 弃用函数第 2 步：在函数体第一行加 lifecycle::deprecate_warn("1.0.0", "old_fun()", "new_fun()")，然后调用 new_fun(x)。
8. 弃用函数第 3 步：在 @examples 中展示迁移，先写旧调用，注释 # ->，再写新调用。
9. 选择弃用函数：deprecate_soft() 用于第一阶段，只警告直接用户和测试期间；deprecate_warn() 是标准弃用，每 8 小时警告一次；deprecate_stop() 是移除前最终阶段，报错并给有用信息。
10. major release 的弃用工作流：搜索 deprecate_stop() 并考虑完全移除函数；把 deprecate_warn() 替换为 deprecate_stop()；把 deprecate_soft() 替换为 deprecate_warn()。
11. 重命名函数：把实现移到新名称，在旧名称中调用新函数并弃用；旧函数加 deprecated badge，说明重命名原因（如 API 一致性），加 @keywords internal 和 @export，函数体第一行调用 lifecycle::deprecate_warn("1.0.0", "add_two()", "number_add()")，然后调用 number_add(x, y)；新函数正常实现并 @export。
12. 弃用参数：把旧参数默认值设为 deprecated()，用 lifecycle::is_present() 检查；若存在，调用 lifecycle::deprecate_warn("1.4.0", "write_file(path)", "write_file(file)")，并把旧参数值赋给新参数；在 @param 中用 deprecated badge 提示改用新参数。
13. 重命名参数：新旧参数同时保留，旧参数默认 deprecated()；用 lifecycle::is_present() 检测旧参数，调用 lifecycle::deprecate_warn("1.0.0", "add_two(na.rm)", "add_two(na_rm)")，把旧值赋给新参数；函数体使用新参数。
14. 替代（supersede）函数：对不应移除但有更好替代的函数，在 @description 加 superseded badge，说明开发已完成并指向替代函数；无需 warning，只需文档说明，并展示等价迁移代码，例如 gather() 与 pivot_longer()。
15. 标记实验性函数：在 @description 加 `r lifecycle::badge("experimental")`；在函数体第一行调用 lifecycle::signal_stage("experimental", "cool_function()")。
16. 测试弃用：用 expect_snapshot() 包住旧函数调用并断言结果，确认其仍工作且发出合适警告；示例 expect_snapshot({ x <- old_fun(1); expect_equal(x, expected_value) })。
17. 在已有测试中抑制弃用警告：用 withr::local_options(lifecycle_verbosity = "quiet") 后继续断言函数值。
18. 为影响多个函数的弃用创建内部 helper：定义 warn_for_verbose(verbose = TRUE, env = rlang::caller_env(), user_env = rlang::caller_env(2))；若 !lifecycle::is_present(verbose) 或 isTRUE(verbose) 则 invisible() 返回；否则调用 lifecycle::deprecate_warn(when = "2.0.0", what = I("The `verbose` argument"), details = c("Set `options(mypkg_quiet = TRUE)` to suppress messages.", "The `verbose` argument will be removed in a future release."), user_env = user_env) 并 invisible()；在受影响函数中用 verbose = deprecated() 并在函数体调用 warn_for_verbose(verbose)。
19. 自定义弃用消息：非标准弃用用 I() 包裹自定义文本；调用 lifecycle::deprecate_warn(when = "1.0.0", what = I('Setting option "pkg.opt" to "foo"'), with = I('"pkg.new_opt"'))；确保 what 片段能与 "was deprecated in..." 拼接。
20. 参考详细阶段定义：查看 references/lifecycle-stages.md 获取 lifecycle 阶段定义和转换。

适用边界 · 注意事项

• 非 R 包开发项目，或未使用 roxygen2/lifecycle 的项目不适用。
• 当没有明确替代方案或迁移路径时，不应强行弃用；对不应移除但有更好替代的函数应使用 superseded 文档说明，而不是 deprecate_* 警告。
• deprecation 阶段升级和移除主要面向 major release；日常小改动或无 API 移除计划时不必执行该流程。