互換性を破る変更のロールアウト ガイド

問題を報告 ソースを表示 Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Bazel に破壊的変更を加えることが必要になります。デザインを変更し、うまく機能していない部分を修正する必要があります。ただし、コミュニティと Bazel エコシステムが追随できるようにする必要があります。そのため、Bazel プロジェクトでは下位互換性ポリシーを採用しています。このドキュメントでは、Bazel のコントリビューターが、このポリシーに準拠するために Bazel に互換性を破る変更を加えるプロセスについて説明します。

  1. 設計ドキュメント ポリシーに準拠します。

  2. GitHub で Issue を報告します。

  3. 変更を適用します。

  4. ラベルを更新する。

  5. リポジトリを更新する。

  6. 互換性なしフラグを反転します。

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 パイプラインを使用します。このパイプラインの仕組みについては、こちらをご覧ください。

Google の開発サポートチームは migration-ready ラベルをモニタリングしています。このラベルを GitHub の問題に追加すると、以下が処理されます。

  1. GitHub Issue にコメントを作成して、移行する必要がある障害とダウンストリーム プロジェクトのリストを追跡します（例を参照）。

  2. GitHub の問題を報告して、互換性のない変更によって破損したすべてのダウンストリーム プロジェクトのオーナーに通知します（例を参照）。

  3. 目標のリリース日までにすべての問題に対処できるようフォローアップする

ダウンストリーム パイプラインでのプロジェクトの移行は、互換性のない変更作成者の責任ではありませんが、以下の方法で移行を加速し、Bazel ユーザーと Bazel Green チームの双方の負担を軽減できます。

  1. PR を送信してダウンストリーム プロジェクトを修正します。

  2. 移行についてサポートが必要な場合は、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 の問題がクローズされるようにします。