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