lifecycle

R パッケージのライフサイクル管理

tidyverse の規約と lifecycle パッケージを使用して、関数と引数のライフサイクルを管理します。

セットアップ

man/figures/ に lifecycle-*.svg ファイルがあるか確認し、lifecycle が設定済みかどうかを確認します。

未設定の場合は、次を実行します。

usethis::use_lifecycle()

これにより、次の処理が行われます。

• DESCRIPTION の Imports に lifecycle を追加します
• パッケージのドキュメントファイルに @importFrom lifecycle deprecated を追加します
• バッジ SVG を man/figures/ にコピーします

ライフサイクルバッジ

roxygen2 のドキュメントにバッジを挿入します。

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

引数の場合：

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

パッケージ全体のステージと異なるステージの関数／引数にのみバッジを付けます。

関数の非推奨化

1. @description にバッジと説明を追加します。

#' Do something
#'
#' @description
#' `r lifecycle::badge("deprecated")`
#'
#' `old_fun()` was deprecated in mypkg 1.0.0. Use [new_fun()] instead.
#' @keywords internal

2. 関数本体の先頭行に deprecate_warn() を追加します。

old_fun <- function(x) {

lifecycle::deprecate_warn("1.0.0", "old_fun()", "new_fun()")
new_fun(x)
}

3. 例で移行方法を示します。

#' @examples
#' old_fun(x)
#' # ->
#' new_fun(x)

非推奨化関数

関数	使用するタイミング
deprecate_soft()	最初のステージ。直接のユーザーとテスト中にのみ警告します
deprecate_warn()	標準的な非推奨化。8 時間ごとに 1 回警告します
deprecate_stop()	削除前の最終ステージ。役立つメッセージとともにエラーになります

メジャーリリースに向けた非推奨化のワークフロー：

1. deprecate_stop() を検索し、関数自体を完全に削除することを検討します
2. deprecate_warn() を deprecate_stop() に置き換えます
3. deprecate_soft() を deprecate_warn() に置き換えます

関数名の変更

実装を新しい名前に移し、古い名前から非推奨化を通知しながら呼び出します。

#' @description
#' `r lifecycle::badge("deprecated")`
#'
#' `add_two()` was renamed to `number_add()` for API consistency.
#' @keywords internal
#' @export
add_two <- function(x, y) {
lifecycle::deprecate_warn("1.0.0", "add_two()", "number_add()")
number_add(x, y)
}

#' Add two numbers
#' @export
number_add <- function(x, y) {
x + y
}

引数の非推奨化

deprecated() をデフォルト値として使用し、is_present() で確認します。

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

引数名の変更

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

関数の置き換え

削除すべきではない、より優れた代替手段がある関数の場合：

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

警告は不要です。推奨する代替手段をドキュメントに記載するだけです。

実験的機能としてマークする

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

非推奨化のテスト

非推奨化された関数が動作し、適切に警告することをテストします。

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

既存のテストでは警告を抑制します。

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

非推奨化ヘルパー

多くの関数に影響する非推奨化（例：共通の引数の削除）では、内部ヘルパーを作成します。

warn_for_verbose <- function(
  verbose = TRUE,
  env = rlang::caller_env(),
  user_env = rlang::caller_env(2)
) {
  if (!lifecycle::is_present(verbose) || isTRUE(verbose)) {
    return(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()
}

その後、影響を受ける関数で使用します。

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

カスタムの非推奨化メッセージ

標準的でない非推奨化には、カスタムテキストを 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...」を付け加えても意味が通る必要があります。

参考資料

各ステージの詳細な定義と移行については、references/lifecycle-stages.md を参照してください。