lifecycle ステージ

Stable

デフォルトの開発段階は (stable) です。 関数は、作者がそのインターフェイスに満足し、大きな問題がなく、喜んで世界と共有できるときに安定したとみなされます。 この段階がデフォルトであるため、安定バッジをつけるのは、その状態に注意を向ける必要がある場合のみです。

安定性 (stable) は、破壊的な変更 (breaking changes) の観点から定義されます。 破壊的な変更 とは、その関数を期待通りに使っているコードを破壊するような変更のことです。 一般に、破壊的な変更は、関数を削除したり、関数の引数を削除したり、有効な入力のセットを減少させることによって、エラーなしで動作するコードのセットを減少させます。 破壊的な変更には、出力型の変更も含まれます。 もし、ある関数への入力のうち、結果を返す（そしてエラーを返さない）可能性のあるものをすべて想像した場合、破壊的な変更はその集合をより小さくします。

関数が動作しなくなるような変更が、すべて壊れる変更というわけではありません。 例えば、誤ってバグに頼ってしまったとします。 そのバグが修正されたとき、あなたのコードは壊れますが、これは破壊的な変更ではありません。 このような動作の変更に対してコードをより堅牢にする良い方法は、関数をその明示的に意図された効果にのみ使用することです。 例えば、c() を使って2つのベクトルを連結することは、明らかにこの関数の意図した使い方なので、あなたのコードを危険にさらすことはありません。 一方、属性の削除という副次的な目的のためだけに c() を使用することは、おそらく良いアイデアではありません。 もし、 c(factor("foo")) を使って因子レベルの整数を取得した場合、 c() が因子メソッドを実装すると、あなたのコードは壊れる危険性があります。

安定した機能には、破壊的な変更に関する2つの約束があります。

• 壊れるような変更は可能な限り避ける。 私たちは、既存のコードを変更することによる短期的な苦痛よりも、変更による長期的な利益が大きいと判断した場合にのみ、破壊的な変更を行います。

• もし破壊的な変更が必要な場合は、次に説明する非推奨のプロセスを通じて、徐々に行われます。 これにより、エラーが発生し始める前にコードを調整する十分な時間が与えられます。

非推奨 (Deprecated)

非推奨 (Deprecated)　の関数は、より良い代替手段があるため、削除が予定されています。 非推奨の関数を呼び出すと、代わりに何を使うべきかを示す警告が表示されます。 例えば、tibble::as_data_frame()を考えてみましょう。

df <- tibble::data_frame(x = 1)
#> Warning message:
#> `data_frame()` is deprecated as of tibble 1.1.0.
#> Please use `tibble()` instead.
#> This warning is displayed once every 8 hours.
#> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was generated. 

非推奨の警告は、その関数がいつ非推奨になったのか（2016年にリリースされた tibble 1.1.0 にて）、代わりに何を使うべきか（tibble()）を教えてくれるものです。 あまり煩わしくならないように、非推奨のメッセージは1セッションにつき1回だけ表示され、それがどこから来たのかは lifecycle::last_lifecycle_warnings() を呼び出すことで正確に知ることができます。 vignette("manage") には、あなたのコードで非推奨の警告を扱うための、より詳しいアドバイスがあります。

特に重要な機能は、さらに2段階の非推奨を受ける場合があります。

• ソフト非推奨は非推奨の前にあります。 これは、その関数の新しい使い方を阻止し、パッケージ開発者がその関数から離れることを奨励するために作られた、より穏やかな非推奨の形式です。 Soft deprecated はパッケージのインターフェイスを変更できるようにし、 ユーザが変更を強いられる前にパッケージ開発者がコードを更新するように促します。

• 非推奨 (deprecated)ß の後には、Defunct が続きます。 ほとんどの場合、非推奨の関数は最終的に削除されるだけです。 これは、その関数は存在し続けるが、非推奨の警告がエラーに変わることを意味します。 これは、単に関数を削除するよりもユーザーフレンドリーな方法です。なぜなら、ユーザーは自分のコードがなぜ動かなくなったのか、どうすれば修正できるのかを説明する明確なエラーメッセージを受け取ることができるからです。

旧式 (superseded)

非推奨に代わるよりソフトな方法として、旧式 (superseded) があります。 旧式¹ 関数にはより良い代替案があることが知られていますが、その関数自体は消え去ったりはしません。 古い関数は警告を発しませんが(使い続けても危険はないので)、代わりに何を推奨するかはドキュメントに書かれています。

旧式の関数には新しい機能は追加されませんが、動作を維持するために必要な重要なバグフィックスは提供されます。 ある意味、旧式の関数は安定版関数よりも安全です。なぜなら、(良くも悪くも) 決して変更されないことが保証されているからです。

実験的 (experimental)

一部の機能は、 (experimental) の段階で公開されます。 実験的な関数は、人々が試してフィードバックを得られるように公開されていますが、長期的な安定性を約束するものではありません。 特に、作者は非推奨のサイクルなしに、破壊的な変更を行う権利を留保します。 とはいえ、人気と安定性の間には何らかの相互作用があります。 人気のある関数を壊すことは、たとえ実験的であると明確に示されていたとしても、広く苦痛を与える可能性が高いので、一般的にそれを避けようとします。

一般的に、バージョン番号が 1.0.0 未満のパッケージは、少なくともいくらか実験的であり、将来的に大きな変更があるかもしれないと考えてよいでしょう。 最も実験的なパッケージは GitHub にしか存在しません。 もしあなたが非CRANパッケージを使用している場合、積極的な関係を計画するべきです: パッケージが変更された場合、あなたのコードを更新する準備をする必要があります。

旧式ステージ

これらのステージは現在では使用していませんが、過去に使用したことがあるため、ここに記録しています。