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,
},
コミットの説明に、フラグの簡単な概要を追加します。また、次の形式で RELNOTES: を追加します。
RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details
コミットでは、コードがドキュメントと一致しないコミット期間がないように、関連するドキュメントも更新する必要があります。ドキュメントはバージョン管理されているため、ドキュメントの変更が誤って早期にリリースされることはありません。
ラベル
commit がマージされ、互換性のない変更を採用する準備ができたら、GitHub の問題にラベル migration-ready を追加します。
フラグに問題が見つかり、ユーザーがまだ移行していない場合: フラグ migration-ready を削除します。
次のメジャー リリースでフラグを反転する場合は、問題に「breaking-change-X.0」というラベルを追加します。
リポジトリを更新する
Bazel CI は、Bazel@HEAD + Downstream で重要なプロジェクトのリストをテストします。これらのほとんどは、他の Bazel プロジェクトの依存関係であることが多いため、より広範なコミュニティの移行をブロックしないように移行することが重要です。これらのプロジェクトの移行ステータスをモニタリングするには、bazelisk-plus-incompatible-flags パイプラインを使用します。このパイプラインの仕組みについては、こちらをご覧ください。
migration-ready ラベルは Google の開発サポートチームがモニタリングしています。このラベルを GitHub の問題に追加すると、次のように処理されます。
GitHub の問題にコメントを作成して、失敗したリストと移行が必要なダウンストリーム プロジェクトを追跡します（例を参照）。
GitHub の問題を報告して、互換性のない変更によって破損したすべてのダウンストリーム プロジェクトのオーナーに通知します（例を参照）。
目標のリリース日までにすべての問題に対処できるようフォローアップする
ダウンストリーム パイプラインのプロジェクトの移行は、互換性のない変更の作成者の責任ではありませんが、次の手順を行うと、移行を加速し、Bazel ユーザーと Bazel Green チームの両方の負担を軽減できます。
PR を送信してダウンストリーム プロジェクトを修正します。
移行についてサポートが必要な場合は、Bazel コミュニティ（Bazel Rules Authors 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 detailscommit の説明の残りの部分に追加情報を含めることができます。 - 説明に
Fixes #xyzを使用して、commit が統合されたときに GitHub の問題がクローズされるようにします。 - ドキュメントを確認し、必要に応じて更新します。
- 新しい問題
#abcを報告して、フラグの削除を追跡します。
フラグの削除
HEAD でフラグが反転されたら、最終的には Bazel から削除されます。互換性のないフラグを削除する予定がある場合:
- 互換性のない大きな変更の場合は、ユーザーが移行する時間を長くすることを検討してください。理想的には、少なくとも 1 つのメジャー リリースでフラグを使用できるようにする必要があります。
- フラグを削除する commit では、説明に
Fixes #abcを使用して、commit が統合されたときに GitHub の問題がクローズされるようにします。