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