Bazel には、互換性を破る変更が必ず発生します。設計を変更し、正しく機能しないものを修正する必要があります。ただし、コミュニティと Bazel エコシステムが対応できるようにする必要があります。そのため、 Bazel プロジェクトでは 下位互換性ポリシーが採用されています。 このドキュメントでは、Bazel コントリビューターがこのポリシーに準拠するために Bazel に互換性を破る変更を加えるプロセスについて説明します。
GitHub の Issue
GitHub の Issue を作成 Bazel リポジトリで。 例をご覧ください。
次のことをおすすめします。
タイトルはフラグの名前で始まる（フラグ名は
incompatible_で始まる）。ラベル
incompatible-changeを追加する。説明には、変更の説明と関連する設計ドキュメントへのリンクを含める。
説明には、ユーザーがコードを更新する方法を説明する移行レシピを含める。変更が機械的な場合は、移行ツールへのリンクを含めることをおすすめします。
説明には、移行しない場合にユーザーに表示されるエラー メッセージの例を含める。これにより、検索エンジンから GitHub の Issue を見つけやすくなります。エラー メッセージが役立ち、対応可能であることを確認してください。 可能であれば、エラー メッセージに互換性のないフラグの名前を含める必要があります。
移行ツールについては、
Buildifierへの投稿をご検討ください。
BUILD、WORKSPACE、.bzl
ファイルに自動修正を適用できます。警告を報告することもあります。
実装
Bazel で新しいフラグを作成します。デフォルト値は false にする必要があります。ヘルプテキストには、GitHub
の Issue の URL を含める必要があります。フラグ名は incompatible_ で始まるため、メタデータタグが必要です。
metadataTags = {
OptionMetadataTag.INCOMPATIBLE_CHANGE,
},
commit の説明に、フラグの簡単な概要を追加します。
また、RELNOTES: を以下の形式で追加します:
RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details
commit では、関連するドキュメントも更新する必要があります。これにより、コードとドキュメントが一致しない commit の期間がなくなります。ドキュメントはバージョン管理されているため、ドキュメントの変更が誤って早期にリリースされることはありません。
ラベル
commit がマージされ、互換性のない変更を導入する準備ができたら、GitHub の Issue に
migration-ready
ラベルを追加します。
フラグに問題が見つかり、ユーザーがまだ移行しない場合は、migration-ready フラグを削除します。
次のメジャー リリースでフラグを切り替える予定の場合は、Issue に `breaking-change-X.0" ラベルを追加します。
リポジトリを更新する
Bazel CI は、
Bazel@HEAD + Downstreamで重要なプロジェクトのリストをテストします。ほとんどは他の
Bazel
プロジェクトの依存関係であることが多いため、移行をブロック解除してより広範なコミュニティに移行することが重要です。これらのプロジェクトの移行ステータスをモニタリングするには、bazelisk-plus-incompatible-flagsパイプラインを使用します。
このパイプラインの仕組みについては、こちらをご覧ください。
Google のデベロッパー サポート チームは migration-ready ラベルをモニタリングしています。このラベルを
GitHub の Issue に追加すると、次の処理が行われます。
GitHub の Issue にコメントを作成して、移行が必要な失敗とダウンストリーム プロジェクトのリストを追跡します（例を参照）
互換性のない変更によって破損したすべてのダウンストリーム プロジェクトのオーナーに通知する GitHub の Issue を作成します（例を参照）
ターゲット リリース日までにすべての問題が解決されるようにフォローアップします。
ダウンストリーム パイプラインでのプロジェクトの移行は、互換性のない変更の作成者の責任ではありませんが、次の操作を行うことで移行を迅速化し、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の下に表示されます。チェックリストのすべての Issue が修正済みまたはクローズ済みとしてマークされている。
ユーザーの懸念や質問が解決されている。
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 の Issue がクローズされます。 - 必要に応じてドキュメントを確認して更新します。
- フラグの削除を追跡する新しい Issue
#abcを作成します。
フラグを削除する
フラグが HEAD で切り替えられたら、最終的に Bazel から削除する必要があります。 互換性のないフラグを削除する予定の場合:
- 互換性のない大きな変更の場合は、ユーザーが移行する時間を長くすることを検討してください。 理想的には、少なくとも 1 つのメジャー リリースでフラグを使用できるようにする必要があります。
- フラグを削除する commit の場合は、説明で
Fixes #abcを使用します。これにより、commit がマージされると GitHub の Issue がクローズされます。