設計ドキュメント

Nightly · 9.1 · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 8.1

ユーザー向けの機能を追加、変更、削除する場合や、Bazel に 大幅なアーキテクチャの変更を加える場合は、変更を送信する前に設計 ドキュメントを作成し、審査を受ける必要があります。

以下に、重大な変更の例を示します。

  • ネイティブ ビルドルールの追加または削除
  • ネイティブ ルールに対する破壊的変更
  • 複数のルールの動作に影響するネイティブ ビルドルールのセマンティクスに対する変更
  • 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 機能の説明については、必ずドキュメントをご覧ください。

コントリビューターのワークフロー

コントリビューターは、設計ドキュメントを作成し、pull リクエストを送信して、提案の審査担当者をリクエストできます。

設計ドキュメントを作成する

すべての設計ドキュメントには、次の情報を含むヘッダーが必要です。

  • 著者
  • 最後の大きな変更の日付
  • 審査担当者のリスト（リード審査担当者 1 名を含む） リード審査担当者
  • 現在のステータス（下書き、審査中、承認済み、却下 実装中、実装済み）
  • ディスカッション スレッドへのリンク（お知らせの後に追記）

ドキュメントは、一般公開されている Google ドキュメント またはMarkdownで作成できます。Markdown と Google ドキュメントの比較については、以下をご覧ください。

ユーザーに影響する提案には、下位互換性への影響を説明するセクション（必要に応じてロールアウト計画）が必要です。

プルリクエストを作成する

設計ドキュメントを共有するには、pull リクエスト（PR）を作成して、ドキュメントを 設計インデックスに追加します。Markdown ファイルまたはドキュメント リンクを 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 関連ドキュメントとの視覚的な一貫性が保たれます。これを行うには、[ファイル] > [コピーを作成] をクリックするか、こちらのリンクをクリックして設計ドキュメント テンプレートのコピーを作成します。

ドキュメントを一般公開するには、 [共有] > [詳細設定] > [変更...] をクリックし、 [オン - リンクを知っている全員] を選択します。ドキュメントでコメントを許可すると、Google アカウントがなくても誰でも匿名でコメントできます。

Markdown を使用する

ドキュメントは GitHub に保存され、 GitHub 版の Markdown （仕様）を使用します。

既存のドキュメントを更新するには、PR を作成します。重大な変更は、ドキュメント審査担当者による審査が必要です。軽微な変更（誤字脱字、書式設定など）は、誰でも承認できます。

審査担当者のワークフロー

審査担当者は、設計ドキュメントにコメントし、審査して承認します。

審査担当者の一般的な責任

設計ドキュメントの審査、必要に応じて追加情報の要求、審査プロセスに合格した設計の承認を行います。

新しいプロポーザルを受け取った場合

  1. ドキュメントを簡単に確認します。
  2. 重要な情報が不足している場合や、設計がプロジェクトの目標に合わない場合は、コメントします。
  3. 追加の審査担当者を提案します。
  4. 審査の準備ができたら、PR を承認します。

審査プロセス中

  1. 問題がある場合や説明が必要な場合は、設計作成者と話し合います。
  2. 必要に応じて、設計を把握しておくべき審査担当者以外のユーザーにコメントを依頼します。
  3. 承認の前提条件として、作成者が対処する必要があるコメントを決定します。
  4. 提案の現在の状態に満足したら、ディスカッション スレッドに「LGTM」（Looks Good To Me）と書き込みます。

すべての設計審査リクエストでこのプロセスに従ってください。設計インデックスにない Bazel に影響する設計は承認しないでください。

リード審査担当者の責任

保留中の設計の実装について、実施するかどうかを決定します。これを行うことができない場合は、適切なデリゲートを特定するか（PR をデリゲートに再割り当て）、バグを Bazel マネージャーに再割り当てして、さらに対応を依頼する必要があります。

審査プロセス中

  1. コメントと設計の反復処理が建設的に進むようにします。
  2. 承認する前に、他の審査担当者の懸念事項が解決されていることを確認します。

すべての審査担当者による承認後

  1. メーリング リストでの発表から少なくとも 1 週間が経過していることを確認します。
  2. PR でステータスが更新されていることを確認します。
  3. 提案作成者から送信された PR を承認します。

設計の却下

  1. PR 作成者に PR を送信してもらうか、PR を送信します。
  2. PR でドキュメントのステータスが更新されます。
  3. 現在の状態で設計を承認できない理由を説明し、次のステップ（「無効な前提条件を見直して再送信する」など）を説明するコメントをドキュメントに追加します。