ユーザー向けの機能の追加、変更、削除や、Bazel のアーキテクチャの大幅な変更を計画している場合は、変更を送信する前に設計ドキュメントを作成し、審査を受ける必要があります。
以下に、重要な変更の例を示します。
- ネイティブ ビルドルールの追加または削除
- ネイティブ ルールの互換性を破る変更
- 複数のルールの動作に影響するネイティブ ビルドルールのセマンティクスの変更
- Bazel のルール定義 API の変更点
- Bazel が他のシステムへの接続に使用する API の変更
- Starlark の言語、セマンティクス、API の変更
- Bazel のパフォーマンスやメモリ使用量に広範な影響を与える可能性がある変更（改善のためか、悪化した場合か）
- 広く使用されている内部 API の変更
- フラグとコマンドライン インターフェースを変更しました。
デザイン レビューを行う理由
設計ドキュメントを作成するときは、他の Bazel デベロッパーと調整を行い、Bazel のコアチームからアドバイスを受けることができます。たとえば、BUILD、WORKSPACE、bzl ファイルで利用可能な関数やオブジェクトを追加、削除、変更する場合は、審査担当者として Starlark チームを追加します。デザイン ドキュメントを提出する前に審査する理由は次のとおりです。
- Bazel は非常に複雑なシステムであり、一見無害に見えるローカルの変化がグローバルに大きな結果をもたらす可能性があります。
- チームはユーザーから多くの機能リクエストを受け取ります。このようなリクエストは、技術的な実現可能性だけでなく、他の機能リクエストに関する重要性も評価する必要があります。
- Bazel の機能は、多くの場合、コアチーム外のユーザーによって実装されています。このようなコントリビューターは、Bazel の専門知識のレベルが大きく異なります。
- Bazel チーム自体の専門知識のレベルはさまざまです。Bazel の 1 つをよく理解しているチームメンバーはいません。
- Bazel を変更する際は、下位互換性を維持し、互換性を破る変更を回避する必要があります。
Bazel の設計レビュー ポリシーは、次のような可能性を高めます。
- すべての機能リクエストがベースライン レベルの審査を受ける。
- 適切に機能しない実装に投資する前に、適切な関係者が設計を検討する。
作業を開始するには、Bazel プロポーザル リポジトリの設計ドキュメントをご覧ください。設計は進行中であるため、実装の詳細は時間の経過とともにフィードバックとともに変更される可能性があります。公開されている設計書には初期設計が反映されています。設計が実装されたときに進行中の変更はありません。現在の Bazel 機能の説明については、必ずドキュメントをご覧ください。
投稿者のワークフロー
コントリビューターは、設計ドキュメントの記述、pull リクエストの送信、提案の審査担当者を作成できます。
設計ドキュメントを作成する
すべての設計ドキュメントには、以下を含むヘッダーが必要です。
- 著者
- 前回のメジャー変更の日付
- 審査担当者（1 人のみ）を含む審査担当者のリスト
- 現在のステータス（下書き、審査中、承認済み、拒否、実装中、実装済み）
- ディスカッション スレッドへのリンク（発表後に追加）
このドキュメントは、誰でも読み取り可能な Google ドキュメントまたは Markdown を使用して作成できます。詳しくは、マークダウンと Google ドキュメントの比較をご覧ください。
ユーザーに表示される影響がある提案には、下位互換性への影響（および必要に応じて展開計画）について記載したセクションが必要です。
pull リクエストの作成
pull リクエスト（PR）を作成して設計ドキュメントを共有し、ドキュメントを設計インデックスに追加します。マークダウン ファイルまたはドキュメント リンクを PR に追加します。
可能であれば、リード レビューアを選択し、他のレビュー担当者を CC に入れてください。リード レビューアを選択しなかった場合は、Bazel 管理者が PR に割り当てます。
PR を作成した後、レビュー担当者がコードレビュー中に仮のコメントを作成できます。たとえば、審査担当者は追加の審査担当者を提案できます。また、不足している情報を指摘することもできます。リード レビュー担当者は、レビュー プロセスを開始できると判断したときに PR を承認します。これは、提案が完璧でも承認されるという意味でもなく、提案にディスカッションを開始するのに十分な情報が含まれていることを意味します。
新しい提案の発表
PR が送信されたら、bazel-dev に通知を送信します。
他のグループ（bazel-discuss など）をコピーして Bazel のエンドユーザーからフィードバックを得ることもできます。
審査担当者による反復処理
ご興味をお持ちであれば、誰でもこの提案にコメントできます。質問に答え、提案を明確にし、懸念事項に対処してください。
お知らせスレッドでディスカッションを行う。プロポーザルが Google ドキュメントにある場合は、代わりにコメントを使用できます（匿名のコメントも使用できます）。
ステータスを更新する
新しい PR を作成して、イテレーションが完了したらプロポーザルのステータスを更新します。PR を同じリードの審査担当者に送信し、他の審査担当者を CC に含めます。
リード レビューアは、他のレビュー担当者が決定に同意したことを確認してから、PR を承認します。
最初の発表から提案の承認までに少なくとも 1 週間かかります。これにより、ユーザーはドキュメントを読んで懸念事項を共有する時間を十分に確保できます。
実装は、概念実証やテストなど、提案が承認される前から開始できます。ただし、審査が完了するまでは変更を送信できません。
リード レビューアの選択
リード レビュー担当者は、次の分野のエキスパートである必要があります。
- 関連するサブシステムに精通している
- 客観的で建設的なフィードバックを提供できること
- 審査期間全体を通してプロセスを主導できる
連絡先でさまざまなチームラベルを確認することを検討します。
マークダウンと Google ドキュメントの比較
どちらの方法も使用できるため、最適な方法を決定してください。
Google ドキュメントを使用するメリット:
- 簡単に開始できるため、ブレインストーミングに効果的
- 共同編集。
- 迅速なイテレーション
- 編集を提案する簡単な方法。
マークダウン ファイルを使用するメリット:
- リンク用のクリーンな URL。
- リビジョンの明示的な記録。
- リンクを設定する前にアクセス権を設定することを忘れないでください。
- 検索エンジンで簡単に検索できます。
- 将来を見据えて: 書式なしテキストは特定のツールに便乗するものではなく、インターネット接続は必要ありません。
- 作成者がいなくなっても更新することが可能です。
- これらは自動的に処理できます（リンクの更新/検出、著者のリストの取得など）。
最初に Google ドキュメントをイテレーションしてから、マークダウンに変換して後処理にすることもできます。
Google ドキュメントの使用
一貫性を保つため、Bazel 設計ドキュメント テンプレートを使用します。このファイルには必要なヘッダーが含まれており、Bazel 関連の他のドキュメントとの視覚的な整合性が確保されています。これを行うには、[File] > [Create a copy] をクリックするか、このリンクをクリックしてデザイン ドキュメント テンプレートのコピーを作成します。
ドキュメントを誰でも閲覧できるようにするには、[共有] > [詳細設定] > [変更] をクリックし、[オン - リンクを知っている全員] を選択します。ドキュメントに対するコメントを許可すると、Google アカウントを持っていなくても、誰でも匿名でコメントできるようになります。
Markdown を使用する
ドキュメントは GitHub に保存され、GitHub の Markdown フレーバー（仕様）が使用されます。
PR を作成して既存のドキュメントを更新する。大幅な変更はドキュメント審査担当者によって審査されます。些細な変更（入力ミス、書式設定など）は、誰でも承認できます。
審査担当者のワークフロー
審査担当者が設計ドキュメントのコメント、レビュー、承認を行います。
一般的な審査担当者の責任
あなたは、設計ドキュメントを確認し、必要に応じて追加情報を要求し、レビュー プロセスに合格した設計を承認する責任があります。
新しい提案を受け取ったとき
- ドキュメントを簡単に確認しましょう。
- 重要な情報が欠落している場合や、設計がプロジェクトの目標に合わない場合は、コメントしてください。
- 追加の審査担当者を提案します。
- PR が審査できるようになったら承認します。
レビュー プロセス中
- 問題のある、または説明する必要のある問題について、設計作成者との話し合いを行います。
- 必要に応じて、設計に留意すべきレビュー担当者以外のコメントを招待します。
- 承認の前提条件として、作成者が対処する必要があるコメントを決定します。
- プロポーザルの現在の状態に問題がなければ、ディスカッション スレッドに「LGTM」（Looks Good To Me）を記述します。
すべての設計レビュー リクエストに対して、このプロセスを行います。設計インデックスにない場合、Bazel に影響する設計は承認しないでください。
リード レビューアの責任
保留中の設計の実装を決定するかどうかは、お客様の責任となります。それができない場合は、適切なデリゲートを識別する（PR をデリゲートに再割り当てする）か、バグを破棄するために Bazel マネージャーに再割り当てする必要があります。
レビュー プロセス中
- コメントと設計の反復プロセスを建設的に進めるようにします。
- 承認する前に、他のレビュー担当者の懸念が解決されていることを確認します。
すべてのレビュー担当者による承認後
- メーリング リストのお知らせから 1 週間以上経過していることを確認します。
- PR がステータスを更新することを確認します。
- プロポーザルの作成者から送信された PR を承認します。
デザインの不承認
- PR 作成者が PR を送信するか、PR を送信します。
- PR がドキュメントのステータスを更新する。
- 現在の状態で設計を承認できない理由を説明するドキュメントと、次のステップがある場合は、その概要を説明します（例: 「無効な前提条件を再検討して再提出」）。