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