Bazel に互換性を破る変更が行われることは避けられません。必要があります。 設計を変更し 正しく機能しないものを修正しますただし、 コミュニティと Bazel エコシステムがついていけるようにするための取り組みです。そのために、 Bazel プロジェクトで、 下位互換性ポリシー。 このドキュメントでは、Bazel コントリビューターが このポリシーに準拠するよう Bazel を変更してください。
GitHub の問題
GitHub の問題を提出する （Bazel リポジトリにあります）。 例をご覧ください。
次のことをおすすめします。
タイトルはフラグの名前で始まります（フラグ名は
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 により関連するドキュメントが更新され、 コードがドキュメントと矛盾しているコミットのウィンドウ。Google の ドキュメントのバージョニングが行われると、ドキュメントに加えられた変更が誤って 可能性があります。
ラベル
commit がマージされ、互換性のない変更を採用する準備が整ったら、ラベルを追加します。
migration-ready
報告します
フラグに問題があり、ユーザーの移行がまだ想定されていない場合:
migration-ready フラグを削除します。
次のメジャー リリースでフラグを反転させる場合は、ラベル「breaking-change-X.0」を追加してください。特定します
リポジトリを更新する
Bazel CI は、
Bazel@HEAD + ダウンストリーム。そのほとんどは
他の Bazel プロジェクトの依存関係を確認できません。そのため、これらのツールを移行して、コミュニティ全体が移行できないようにすることが重要です。これらのプロジェクトの移行ステータスをモニタリングするには、bazelisk-plus-incompatible-flags パイプラインを使用します。
このパイプラインの仕組みをこちらでご確認ください。
Google の開発サポートチームは migration-ready ラベルをモニタリングしています。このラベルを GitHub の問題に追加すると、以下が処理されます。
GitHub Issue にコメントを作成して、移行する必要がある障害とダウンストリーム プロジェクトのリストを追跡します（例を参照）。
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 の説明の残りの部分に追加情報を含めることができます。 - GitHub の問題がクローズされるように、説明に
Fixes #xyzを使用する おすすめします - 必要に応じてドキュメントを確認し、更新します。
- フラグの削除を追跡するには、新しい問題
#abcを提出します。
フラグの削除
フラグが HEAD で反転した後、最終的に Bazel から削除する必要があります。 互換性のないフラグを削除する場合:
- 互換性のない重大な変更の場合は、ユーザーの移行により多くの時間を費やすことを検討してください。 少なくとも 1 つのメジャー リリースでフラグが利用可能になっているのが理想的です。
- フラグを削除する commit の場合は、説明に
Fixes #abcを使用します。 commit がマージされたときに GitHub の問題がクローズされるようにします。