Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

機能の安定化

  • ステータス: 現行
  • 最終更新日: 2022-05-27

機能の安定化には、#[stable] 属性の追加が伴います。これは、新しいトレイト実装とともに導入される場合もあれば、既存の #[unstable] 属性を置き換える場合もあります。

安定化は Libs FCP（Final Comment Period）プロセスを経て行われます。これは通常、その機能の tracking issue 上で行われます。

FCP が適切なのはいつか？

不安定機能の API 設計空間（例: 代替 API）が完全に検討され、未解決の懸念がない状態になったら、誰でもその安定化を推進できます。

機能が安定化の準備ができているかどうか分からない場合、最初のステップは、関連する tracking issue で質問し、その議論に参加している他の人から支援を受けることです。場合によっては、その tracking issue に他のアクティブな参加者があまりいないこともあります。そのため、フィードバックを得るのに困っている場合は、支援を依頼するために libs チームのレビューアー のいずれかに直接 ping してください。

安定化レポート

機能が安定化の準備ができたら、FCP プロセスの最初のステップは安定化レポートを書くことです。安定化レポートは必須ではありませんが、強く推奨されており、ライブラリ API チームのメンバーが必要だと判断した場合には必須とされることがあります。安定化レポートの目的は、レビューアーがより迅速に判断できるようにし、リリースノートで安定化された API を文書化するプロセスを簡素化することです。安定化レポートは、主に実装履歴、API 概要、経験レポートの 3 つのセクションで構成されます。

実装履歴セクションでは、実装 PR における最初の議論、最初の実装以降にその機能に加えられたすべての変更、その機能の存続期間中に提起されたすべての issue、およびそれらがどのように解決されたかを要約する必要があります。

API 概要セクションには、標準ライブラリに導入される API の正確な説明を含める必要があります。最新の状態であれば、多くの場合、トップレベルのコメントへの単純なリンクで十分です。ただし、安定化レポートの作成者が tracking issue 自体の作成者ではない場合など、状況によっては、古い情報を修正するために元の tracking issue を編集できないことがあります。

libs チームは、このための cargo unstable-api というツールを保守しており、場合によってはこれを使用して API 概要を生成できます。注意 現在のこのツールの実装は壊れやすく、すべての場合に機能するわけではありません。将来的には、rustdoc または rustc 自身の API のいずれかの上に構築された、より永続的なバージョンのこのツールを用意したいと考えています。

経験レポートセクションには、その機能を使いたいと考え、自分たちのニーズに合うことをテストしたユーザーの具体的なユースケースを含める必要があります。経験レポートには、その機能を使用した経験の簡単な要約を含める必要があります。理想的には、その機能をプロジェクトに統合したコミットやブランチへのリンクを含めるべきですが、これは要件ではありません。別の方法として、安定化されるものと同一の API をエクスポートする crate の使用例をユーザーが提供することもできます。

安定化レポートの例は #88581 で確認できます。

機能を安定化する PR を書く前に

まず FCP が完了しているか確認してください。完了していない場合は、rust-lang organization のメンバーであれば @rust-lang/libs-api に ping するか、 その機能の状況について尋ねるコメントを残してください。

これにより、安定化 PR を開いた後、FCP プロセスが進行する間に定期的なリベースが必要になる事態を避けられます。

部分的な安定化

既存の機能のサブセットのみを安定化したい場合は、新しい tracking issue の作成を省略し、代わりに安定化される機能のサブセットに対する部分的な安定化 PR を作成する必要があります。

機能が部分的な安定化の準備ができているかどうか分からない場合、最初のステップは、関連する tracking issue で質問し、その議論に参加している他の人から支援を受けることです。場合によっては、その tracking issue に他のアクティブな参加者があまりいないこともあります。そのため、フィードバックを得るのに困っている場合は、支援を依頼するために libs チームのレビューアー のいずれかに直接 ping してください。

tracking issue #71146 と部分的な安定化 PR #94640 で、機能を部分的に安定化する例を確認できます。

const が関係する場合

const 関数は、#[rustc_const_unstable] 属性を #[rustc_const_stable] 属性に置き換える PR で安定化できます。const 性がコミットしたいものであるかどうかについて意見を求めるために、Constant Evaluation WG に ping する必要があります。公開される intrinsic が const 安定化される場合は、@rust-lang/lang も FCP に含める必要があります。

その関数が内部的に #[allow_internal_unstable] 属性を通じて他の不安定な const 関数に依存しているかどうかを確認し、内部的に不安定な呼び出しが削除された場合にその関数をどのように実装できるかを検討してください。#[allow_internal_unstable] の詳細については、Stability attributes ページを参照してください。

unsafe と const が関係する場合、たとえば「unconst」な操作では、その使用に関する const safety の議論も文書化される必要があります。つまり、const fn には追加の決定性（例: 実行時/コンパイル時の結果が対応していなければならず、関数の出力は入力のみに依存する、など）の制約があり、それらは維持されなければならず、unsafe が使用される場合にはそれらについて論じる必要があります。

ライブラリ機能の安定化 PR

機能を安定化することを決定したら、その安定化を実際に行う PR が必要です。この種の PR は、通常は属性を更新するだけの小さなものなので、Rust に関わるための非常に良い方法です。

以下は、機能を安定化する方法の一般的なガイドです。もちろん、機能はそれぞれ異なるため、一部の機能ではこのガイドで述べている内容を超える手順が必要になる場合があります。

アイテムの安定性属性を更新する

ライブラリアイテムは、次のように #[unstable] 属性によって不安定としてマークされます。

#[unstable(feature = "total_cmp", issue = "72599")]
pub fn total_cmp(&self, other: &Self) -> crate::cmp::Ordering { ... }

これを、バージョンをプレースホルダー CURRENT_RUSTC_VERSION に設定した #[stable] 属性に変更する必要があります。

#[stable(feature = "total_cmp", since = "CURRENT_RUSTC_VERSION")]

他の #[stable] 属性には明示的なバージョン番号が含まれている場合がありますが、pull request がマージされるまでに古くなる可能性があるため、バージョン番号を明示的に書いてはいけません。

doctest から feature gate を削除する

安定化されるアイテム上のすべての doctest は不安定機能を有効にしています。そのため、安定化された今では、それらの属性は不要であり、削除する必要があります。

 /// # 例
 ///
 /// ```
-/// #![feature(total_cmp)]
-///
 /// assert_eq!(0.0_f32.total_cmp(&-0.0), std::cmp::Ordering::Greater);
 /// ```

これらを見つける最も明らかな場所は item 自体ですが、ライブラリ全体を検索する価値があります。多くの場合、テストでそれを使用していた他の不安定なメソッドも見つかります。

コンパイラから feature gate を削除する

コンパイラは nightly feature が許可された状態でビルドされるため、そこでもその feature の使用が見つかることがあります。これらも削除する必要があります。

 #![feature(once_cell)]
 #![feature(never_type)]
-#![feature(total_cmp)]
 #![feature(trusted_step)]
 #![feature(try_blocks)]

安定化 PR チェックリスト

feature を安定化するには、次の手順に従ってください。

  1. 安定化する feature のトラッキング issue に安定化レポートを作成します。
  2. （任意）部分的な安定化の場合は、安定化する issue のサブセットについて、新しい部分安定化 PR を作成します。
  3. @rust-lang/libs-api のメンバーに依頼して、トラッキング issue で FCP を開始してもらい、FCP が完了するまで待ちます（disposition-merge 付き）。
  4. #[unstable(...)] を #[stable(since = "CURRENT_RUSTC_VERSION")] に変更します。ここでの CURRENT_RUSTC_VERSION は文字どおりの意味であり、明記されたバージョン番号に置き換えるものではありません。
  5. この API のテストまたは doc-test から #![feature(...)] を削除します。その feature がコンパイラまたはツールで使用されている場合は、そこからも削除します。
  6. 該当する場合は、#[rustc_const_unstable(...)] を #[rustc_const_stable(since = "CURRENT_RUSTC_VERSION")] に変更します。
  7. rust-lang/rust に対して PR を開きます。
    • 適切なラベルを追加します: @rustbot modify labels: +T-libs-api。
    • “Closes #XXXXX” を追加して、トラッキング issue にリンクします。

feature を安定化する例は、FCP 付きのトラッキング issue #81656 と、関連する 実装 PR #84642 で確認できます。