ユーザー向け機能を追加、変更、削除する予定がある場合、または Bazel のアーキテクチャに大きな変更を加える場合は、変更を送信する前に設計ドキュメントを作成して審査を受ける必要があります。
主な変更点の例を次に示します。
- ネイティブ ビルドルールの追加または削除
- ネイティブ ルールの互換性を破る変更
- 1 つ以上のルールの動作に影響するネイティブ ビルドルールのセマンティクスの変更
- Bazel のルール定義 API の変更
- Bazel が他のシステムへの接続に使用する API の変更
- Starlark 言語、セマンティクス、API の変更
- Bazel のパフォーマンスやメモリ使用量に広範囲に影響する可能性がある変更（良い方向でも悪い方向でも）
- 広く使用されている内部 API の変更
- フラグとコマンドライン インターフェースの変更。
設計レビューの理由
設計ドキュメントを作成する場合は、他の Bazel デベロッパーと連携し、Bazel のコアチームにガイダンスを求めることができます。たとえば、提案で BUILD、WORKSPACE、bzl ファイルで使用可能な関数またはオブジェクトを追加、削除、変更する場合は、Starlark チームをレビュー担当者として追加します。設計ドキュメントは、提出前に審査されます。その理由は次のとおりです。
- Bazel は非常に複雑なシステムです。一見無害なローカル変更が、グローバルに大きな影響を与える可能性があります。
- チームはユーザーから多くの機能リクエストを受けます。このようなリクエストは、技術的な実現可能性だけでなく、他の機能リクエストとの関連性も考慮して評価する必要があります。
- Bazel の機能は、コアチーム外のユーザーによって実装されることがよくあります。このようなコントリビューターは、Bazel の専門知識のレベルが大きく異なります。
- Bazel チーム自体の専門知識のレベルはさまざまであり、どのチームメンバーも Bazel の隅々まで完全に理解しているわけではありません。
- Bazel の変更は、下位互換性を考慮し、破壊的な変更を回避する必要があります。
Bazel の設計レビュー ポリシーは、次の可能性を最大限に高めるのに役立ちます。
- すべての機能リクエストは、ベースライン レベルの精査を受けます。
- 適切な人が設計に意見を述べ、機能しない可能性がある実装に投資する前に検討します。
始めるにあたっては、Bazel Proposals リポジトリの設計ドキュメントをご覧ください。設計は現在進行中であるため、実装の詳細は時間の経過とともに、またフィードバックに基づいて変更される可能性があります。公開された設計ドキュメントには、設計が実装されるにつれて進行中の変更は含まれません。現在の Bazel 機能の説明については、必ずドキュメントをご覧ください。
コントリビューターのワークフロー
コントリビューターは、設計ドキュメントの作成、プル リクエストの送信、提案の審査担当者のリクエストを行うことができます。
設計ドキュメントを作成する
すべての設計ドキュメントには、次の情報が含まれるヘッダーが必要です。
- 著者
- 最終的な変更日
- 審査担当者のリスト（1 人（1 人のみ）のリード審査担当者を含む）
- 現在のステータス（下書き、審査中、承認済み、不承認、実装中、実装済み）
- ディスカッション スレッドへのリンク（お知らせ後に追加されます）
ドキュメントは、世界中のユーザーが読み取り可能な Google ドキュメントとして、またはマークダウンを使用して作成できます。詳しくは、Markdown と Google ドキュメントの比較をご覧ください。
ユーザーに影響する提案には、下位互換性への影響（必要に応じてロールアウト計画）を記述するセクションが必要です。
pull リクエストを作成する
プル リクエスト（PR）を作成してドキュメントを設計インデックスに追加し、設計ドキュメントを共有します。マークダウン ファイルまたはドキュメントのリンクを PR に追加します。
可能であれば、リード レビュー担当者を選択し、他のレビュー担当者に Cc を設定します。リード レビュー担当者を選択しない場合、Bazel メンテナンス担当者が PR にリード レビュー担当者を割り当てます。
PR を作成すると、レビュー担当者はコードレビュー中に予備的なコメントを追加できます。たとえば、リード レビュー担当者は、追加のレビュー担当者を提案したり、不足している情報を指摘したりできます。リード レビュー担当者は、審査プロセスを開始できると判断した場合に PR を承認します。これは、提案が完璧であるか、承認されるという意味ではありません。議論を開始するのに十分な情報が提案に含まれていることを意味します。
新しい提案を発表する
PR が送信されたら、bazel-dev に通知を送信します。
他のグループ（Bazel エンドユーザーからのフィードバックを得るための bazel-discuss など）をコピーすることもできます。
審査担当者とやり取りする
提案に興味がある人は誰でもコメントできます。質問に答え、提案を明確にし、懸念事項に対処します。
ディスカッションはお知らせのスレッドで行ってください。提案書が Google ドキュメントにある場合は、代わりにコメントを使用できます（匿名コメントが許可されています）。
ステータスを更新する
イテレーションが完了したら、新しい PR を作成して提案のステータスを更新します。同じリード レビュー担当者に PR を送信し、他のレビュー担当者にも Cc で送信します。
提案を正式に承認するには、リード レビュー担当者が他のレビュー担当者が決定に同意していることを確認したうえで、PR を承認します。
最初のお知らせから提案の承認までの間に、少なくとも 1 週間の期間が必要です。これにより、ユーザーはドキュメントを読み、懸念事項を共有するのに十分な時間を確保できます。
提案が承認される前に、概念実証やテストなどとして実装を開始できます。ただし、審査が完了する前に変更を送信することはできません。
リード審査担当者の選択
リード レビュー担当者は、次の条件を満たすドメイン エキスパートである必要があります。
- 関連するサブシステムに関する知識
- 客観的で、建設的なフィードバックを提供できる
- 審査期間全体にわたってプロセスを主導できる
さまざまなチームラベルが設定されている連絡先を確認することをおすすめします。
Markdown と Google ドキュメント
どちらも使用可能であるため、ご自身にとって最適なものを選択してください。
Google ドキュメントを使用するメリット:
- 簡単に始められるため、ブレインストーミングに効果的です。
- 共同編集。
- 迅速なイテレーション。
- 編集を提案する簡単な方法。
Markdown ファイルを使用するメリット:
- リンク用に 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 によってドキュメントのステータスが更新されます。
- ドキュメントにコメントを追加して、現在の状態で設計を承認できない理由を説明し、次のステップ（「無効な前提条件を見直して再送信」など）を概説します。