ユーザー向けの機能を追加、変更、削除する場合、または 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 によってドキュメントのステータスが更新されます。
- 現在の状態では設計を承認できない理由を説明し、次のステップ（「無効な前提条件を見直して再送信する」など）があれば、その概要を説明するコメントをドキュメントに追加します。