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 により関連ドキュメントも更新する必要があります。Google のドキュメントはバージョン管理されているため、ドキュメントに加えた変更が意図せず早期にリリースされることはありません。
ラベル
commit がマージされ、互換性のない変更を導入する準備が整ったら、GitHub の問題にラベル migration-ready を追加します。
フラグに問題があり、ユーザーの移行がまだ想定されていない場合は、フラグ migration-ready を削除します。
次回のメジャー リリースでフラグを切り替える場合は、問題に「breaking-change-X.0」ラベルを追加してください。
リポジトリを更新する
Bazel CI では、Bazel@HEAD + Downstream で重要なプロジェクトのリストをテストします。それらのほとんどは他の Bazel プロジェクトの依存関係であることが多いため、他の Bazel プロジェクトとの依存関係があるので、他の Bazel プロジェクトに移行して、移行の妨げとならないようにすることが重要です。
これらのプロジェクトの移行ステータスをモニタリングするには、bazelisk-plus-incompatible-flags パイプラインを使用します。このパイプラインの仕組みはこちらで確認できます。
ダウンストリームのパイプラインでのプロジェクトの移行は、互換性のない変更作成者が完全に行う責任ではありません。ただし、移行を加速し、Bazel ユーザーと Bazel グリーンチームの双方の作業を容易にするには、以下を行うことができます。
- GitHub の問題を報告して、互換性のない変更によって壊れたダウンストリーム プロジェクトのオーナーに通知します。
- 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 detailsです。commit の説明の残りの部分には追加情報を含めることができます。 - 説明に
Fixes #xyzを使用して、commit がマージされたときに GitHub の問題がクローズされるようにします。 - ドキュメントを確認し、必要に応じて更新します。
- フラグの削除を追跡するには、新しい問題
#abcを提出します。
フラグの削除
フラグが HEAD で反転された後は、最終的に Bazel から削除する必要があります。 互換性のないフラグを削除する場合:
- 互換性のない重大な変更の場合は、ユーザーの移行時間を確保することを検討してください。理想的には、このフラグは少なくとも 1 つのメジャー リリースで利用できるべきです。
- フラグを削除する commit では、説明に
Fixes #abcを使用し、commit がマージされたときに GitHub の問題がクローズされるようにします。