Bazel に互換性のない変更を加えることは避けられません。デザインを変更し、うまくいかない部分を修正する必要があります。しかし、コミュニティと Bazel のエコシステムがそれに沿うようにする必要があります。この目的のために、Bazel プロジェクトで下位互換性ポリシーが採用されました。このドキュメントでは、Bazel コントリビューターが Bazel で互換性を破ってこのポリシーを遵守するためのプロセスについて説明します。
GitHub の問題
Bazel リポジトリで GitHub の問題を提出します。例を見る
次のように設定することをおすすめします。
タイトルはフラグの名前で始まります（フラグ名は
incompatible_で始まります）。ラベル
incompatible-changeを追加します。説明には、変更の説明と、関連する設計ドキュメントへのリンクが含まれます。
説明には、ユーザーにコードの更新方法を説明するための移行レシピが含まれています。変更が機械的な場合は、移行ツールへのリンクを含めるのが理想的です。
この説明には、ユーザーが移行しない場合に表示されるエラー メッセージの例が含まれています。これにより、検索エンジンで GitHub の問題を検出しやすくなります。エラー メッセージが有用で実用的な内容であることを確認します。 可能であれば、互換性のないフラグの名前がエラー メッセージに含まれています。
移行ツールについては、Buildifier への投稿を検討してください。BUILD、WORKSPACE、.bzl の各ファイルに自動的に修正を適用することができます。また、警告が報告されることもあります。
実装
Bazel で新しいフラグを作成します。デフォルト値は false である必要があります。ヘルプテキストには、GitHub の問題の URL を含める必要があります。フラグ名が incompatible_ で始まるため、メタデータタグが必要です。
metadataTags = {
OptionMetadataTag.INCOMPATIBLE_CHANGE,
},
commit の説明に、フラグの簡単な説明を追加します。また、次の形式で RELNOTES: を追加します。
RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details
また、コードがドキュメントと一致しない commit の時間枠がなくなるように、関連するドキュメントも commit する必要があります。ドキュメントがバージョニングされているので、ドキュメントの変更は意図せず早くリリースされません。
ラベル
commit がマージされ、互換性のない変更を導入する準備ができたら、ラベル migration-ready を GitHub の問題に追加します。
フラグに問題が見つかった場合、まだユーザーが移行しないと想定される場合は、フラグ migration-ready を削除します。
次のメジャー リリースでフラグを変更する予定がある場合は、ラベルに「breaking-change-X.0」を追加してください。
リポジトリを更新する
Bazel CI は、重要なプロジェクトのリストを Bazel@HEAD + ダウンストリームでテストします。大半は他の Bazel プロジェクトの依存関係であることが多く、移行してより広範なコミュニティの移行のブロックを解除することが重要です。これらのプロジェクトの移行ステータスをモニタリングするには、bazelisk-plus-incompatible-flags パイプラインを使用します。こちらで、このパイプラインの仕組みを確認してください。
Google のデベロッパー サポートチームが migration-ready ラベルをモニタリングしています。このラベルを GitHub の問題に追加すると、以下が処理されます。
GitHub の問題にコメントを作成して、移行する必要がある障害とダウンストリーム プロジェクトのリストを追跡します（例を参照）。
GitHub に問題を報告して、互換性のない変更によって破損したすべてのダウンストリーム プロジェクトの所有者に通知する（例を参照）
リリース予定日までにすべての問題に対処したことを確認するためのフォローアップ
ダウンストリーム パイプラインでのプロジェクトの移行に、互換性のない変更作成者の責任は一切ありませんが、以下の操作によって移行を加速し、Bazel ユーザーと Bazel グリーンチームの両方にとって負担を軽減できます。
PR を送信してダウンストリーム プロジェクトを修正します。
移行についてサポートが必要な場合は、Bazel コミュニティ（Bazel ルール作成者 SIG）に問い合わせる。
フラグの反転
フラグのデフォルト値を true に切り替える前に、次の点を確認してください。
エコシステムのコア リポジトリが移行されます。
bazelisk-plus-incompatible-flagsパイプラインでは、フラグはThe following flags didn't break any passing Bazel team owned/co-owned projectsの下に表示されます。チェックリストの問題はすべて修正済みまたはクローズとしてマークされます。
お客様の懸念と質問が解決されました。
フラグを Bazel で処理する準備ができていても、Google での内部移行がブロックされている場合は、内部の blazerc ファイルでフラグ値を false に設定して、フラグの反転をブロックすることを検討してください。これにより、Bazel のユーザーはできるだけ早く新しい動作に依存するようになります。
フラグのデフォルトを true に変更する場合は、次の操作を行います。
- 次の形式で、commit の説明に
RELNOTES[INC]を使用します。RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for details。commit の説明の残りの部分に追加情報を含めることができます。 - 説明に
Fixes #xyzを使用して、commit がマージされたときに GitHub の問題を閉じるようにします。 - 必要に応じて、ドキュメントを確認して更新します。
- 新しい問題
#abcを報告して、フラグの削除を追跡します。
フラグを削除する
フラグを HEAD で反転すると、最終的に Bazel から削除されます。非互換性フラグを削除する場合:
- 互換性のない大規模な変更の場合は、ユーザーが移行できるようにより多くの時間を残すことを検討してください。フラグは少なくとも 1 つのメジャー リリースで取得できることが理想的です。
- フラグを削除する commit では、説明で
Fixes #abcを使用して、commit がマージされたときに GitHub の問題を閉じるようにします。