機能のライフサイクル

問題の特定

標準ライブラリへの変更を提案する前の最初のステップは、解決しようとしている問題を適切に特定することです。これにより、標準ライブラリへの変更を必要とせず、より良い解決策が存在する XY problem のケースを特定しやすくなります。

このため、API設計に関する理論上の懸念ではなく、実際に人々が直面している現実の問題に焦点を当てることが有用です。

標準ライブラリへの適合性

crates.io 上のサードパーティクレートとは異なり、Rust標準ライブラリはバージョン付けされていません。これは、追加された安定APIは、後方互換性のない方法で決して削除または変更できないことを意味します。このため、標準ライブラリのメンテナーは、標準ライブラリAPIへのあらゆる変更に高い基準を設けています。

標準ライブラリに適しているAPIは、言語やコンパイラのサポートを必要とするもの、または既存の標準ライブラリ型を拡張するものです。時間とともに進化することが想定される複雑なAPI（例: GUIフレームワーク）は、バージョン付けがないため適していません。

API変更提案プロセスは、新しいAPIを標準ライブラリに追加するための軽量な最初のステップとなることを意図しています。このプロセスの目的は、提案されたAPI変更が成功する可能性を最大化することです。ACPプロセスは、すべての変更がライブラリAPIチームによってレビューされることを保証することでこれを実現します。ライブラリAPIチームは提案を評価し、その提案がマージされ、最終的なFCPを通過すると楽観視できる場合に受け入れます。

rust-lang/libs-team リポジトリでは、このissueテンプレートを使用してACPを作成できます。これには提案するAPIの概略を含めるべきですが、実装される最終的な設計である必要はありません。

ACPは厳密に必須ではないことに注意してください。提案するAPIの実装を含むpull requestをそのまま提出することもできますが、ライブラリチームが最終的にこの機能を却下した場合、労力が無駄になるリスクがあります。ただし、このリスクはACPが受け入れられた場合でも常に存在することに注意してください。ライブラリチームは、安定化プロセスの後半で機能を却下する可能性があるためです。

API設計の検討

機能が標準ライブラリに含めるのに適していると判断されたら、それをRust APIとして表現する最善の方法を見つけるために、正確な設計を反復的に検討するべきです。この反復的な検討は、コミュニティのすべてのメンバーがコメントし改善を提案できる、Rust internals のようなコミュニティフォーラムで行うべきです。

議論の際には、以下の点を念頭に置いてください。

• 汎用性と具体性のバランスを取るようにしてください。
  • 過度に汎用的なAPIは、一般的なユースケースで使いにくくなる傾向があり、APIサーフェスも複雑になります。これによりレビューや保守が難しくなり、外部クレートの方が適している可能性があります。
  • 過度に具体的なAPIは、一般的なユースケースをすべてカバーできず、将来的にそれらのユースケースに対応するための追加のAPI変更が必要になる可能性があります。
• 常に検討すべき代替案は、この機能を単にサードパーティクレートで追加することです。標準ライブラリ型に新しいメソッドを追加する場合でも、拡張トレイトを使用することでこれは可能です。
• 既存のAPIで既に可能なことの単なる短縮形である「便利」関数の場合、標準ライブラリのサーフェスを拡張するコストを、新しい関数によるエルゴノミクス上の影響と比較して検討するべきです。
  • たとえば、ある型に便利メソッドが多すぎると、ドキュメントを閲覧しにくくなります。
  • さらに、言語レベルの改善によって不要になった場合に、このメソッドが将来非推奨になる可能性が高いかどうかを検討してください。

ライブラリチーム自体はこの議論に直接関与しませんが、個々のメンバーがフィードバックを提供するためにコメントすることがあります。ACP以降に大きな変更があった場合、この時点で別のACPを提案し、ライブラリAPIチームに設計を検証してもらうことができます。

実装

API設計空間の検討が済んだら、有力な解決策に基づく実装を rust-lang/rust リポジトリへのpull requestとして提案するべきです。

pull requestには、検討された代替案の概要を含めるべきです。これにより、レビューの一環として同じ検討作業を繰り返すことを避けられるため、レビュアーにとって有用です。これがない状態で提出されたPRは、より多くの代替案を検討するよう求められてクローズされる場合があります。

提案された機能についてACPが提出されていない場合、そのPRは、標準ライブラリへの適合性を判断するためにライブラリAPIチームによってレビューされる必要があります。

追跡と安定化

PRがマージされる前に、その機能の安定化までの進捗を追跡するtracking issueを開くよう求められます。

これには2つの例外があります。

• 既存の不安定APIの変更では、このAPIの既存のtracking issueを再利用できます。
• 即座に安定となる変更（例: 安定型に対するトレイト実装）にはtracking issueは必要ありません。ただし、そのような変更では不安定期間中にAPIを調整する機会がないため、追加の慎重な精査が必要です。