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

問題を報告する ソースを表示 Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

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

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

  2. GitHub の問題を報告します。

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

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

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

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

  3. 目標リリース日までにすべての問題が解決されるようフォローアップする

ダウンストリーム パイプラインでのプロジェクトの移行は、互換性のない変更の作成者の責任だけではありませんが、移行を加速し、Bazel ユーザーと Bazel Green Team の両方の負担を軽減するために、次の操作を行うことができます。

  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 の issue がクローズされるようにします。
  • 必要に応じてドキュメントを確認して更新します。
  • 新しい問題 #abc を作成して、フラグの削除を追跡します。

フラグを削除する

HEAD でフラグが反転されたら、最終的に Bazel から削除されるはずです。互換性のないフラグを削除する予定がある場合:

  • 互換性のない大きな変更の場合は、ユーザーが移行するまでの期間を長くすることを検討してください。理想的には、フラグは少なくとも 1 つのメジャー リリースで利用可能であるべきです。
  • フラグを削除する commit では、説明に Fixes #abc を使用して、commit がマージされたときに GitHub の問題がクローズされるようにします。