ユーザー向けの機能を追加、変更、削除する場合や、 重要なアーキテクチャの変更が伴う場合は、設計を記述する必要があります。 変更を提出する前に、その内容を確認し、審査を受けます。
重要な変更の例を次に示します。
- ネイティブ ビルドルールの追加または削除
- ネイティブ ルールの互換性を破る変更
- ネイティブ ビルドルール セマンティクスの変更により、より多くの 適用できます。
- 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 人のリード審査担当者のみを含む）
- 現在のステータス（下書き、審査中、承認済み、不承認、 実装中、実装）
- ディスカッション スレッドへのリンク（お知らせ後に追加されます）
ドキュメントは、世界中のユーザーが読み取り可能な Google ドキュメントとして、またはマークダウンを使用して作成できます。Markdown と Google ドキュメントの比較については、以下をご覧ください。
ユーザーに見える影響のある提案には、 下位互換性への影響（および必要に応じてロールアウト計画）
pull リクエストを作成する
プル リクエスト（PR）を作成してドキュメントを設計インデックスに追加し、設計ドキュメントを共有します。追加 マークダウン ファイルまたは PR へのドキュメントのリンクを記載してください。
可能であれば、リード審査担当者を選定します。 他のレビュアーを CC に含めますリードレビュアーを選ばない場合は、Bazel 管理者が PR に割り当てます。
PR を作成した後、レビュー担当者はコードレビュー中に予備的なコメントを追加できます。たとえば、リード レビュアーは、追加のレビュアーを提案したり、不足している情報を指摘したりできます。リード レビュー担当者は、審査プロセスを開始できると判断した場合に PR を承認します。その提案が完璧というわけではない 承認される可能性がある。そのプロポーザルには 取引に必要な 十分な情報が ディスカッションを開始できます。
新しい提案を発表する
PR が送信されたら、bazel-dev に通知を送信します。
他のグループ（例: bazel-discuss、 Bazel エンドユーザーからフィードバックを得ることもできます）。
審査担当者とやり取りする
関心のあるユーザーなら誰でも提案にコメントできます。質問に答え、提案を明確にし、懸念事項に対処します。
ディスカッションはお知らせスレッドで行う必要があります。提案が 代わりにコメントを使用することもできます（匿名のコメントは 許可されています）。
ステータスを更新する
イテレーションが完了したら、新しい PR を作成して提案のステータスを更新します。PR を同じリード審査担当者に送り、他の審査担当者を CC に含める。
提案を正式に承認するには、リード レビュー担当者が他のレビュー担当者が決定に同意していることを確認したうえで、PR を承認します。
最初のお知らせから提案の承認までの間に、少なくとも 1 週間の期間が必要です。これにより、ユーザーはドキュメントを読み、懸念事項を共有するのに十分な時間を確保できます。
実装は、提案の承認前（ テストになりますただし、変更を送信することはできません。 おすすめします
リードレビュアーの選定
リード審査担当者は、次のようなドメイン エキスパートである必要があります。
- 関連するサブシステムに関する知識
- 客観的で、建設的なフィードバックを提供できる
- 審査期間全体にわたってプロセスを主導できる
さまざまなチームラベルが設定されている連絡先を確認することをおすすめします。
Markdown と Google ドキュメント
どちらも使用可能であるため、ご自身にとって最適なものを選択してください。
Google ドキュメントを使用するメリット:
- 簡単に始められるため、ブレインストーミングに効果的です。
- 共同編集。
- 迅速なイテレーション。
- 編集内容を簡単に提案できます。
Markdown ファイルを使用するメリット:
- リンク用に URL をクリーンアップする。
- リビジョンの明示的な記録。
- リンクを公開する前にアクセス権限を設定する必要はありません。
- 検索エンジンで簡単に検索できます。
- 将来性: プレーンテキストは特定のツールに依存せず、インターネット接続も必要ありません。
- 作成者が不在の場合でも、更新できます。
- リンクは自動的に処理され（無効なリンクの更新/検出、 著者名のリストなど）。
最初に Google ドキュメントを反復処理してから、それを 後継のためのマークダウン。
Google ドキュメントの使用
一貫性を保つために、Bazel 設計ドキュメント テンプレートを使用してください。 必要なヘッダーが含まれており、他の Bazel 関連ドキュメントとの視覚的な整合性が確保されています。これを行うには、[ファイル] > [コピーを作成] をクリックするか、このリンクをクリックして設計ドキュメント テンプレートのコピーを作成します。
ドキュメントを読みやすくするには、[ 共有 >詳細設定 >Change... [オン - リンクを知っている全員] を選択します。ドキュメントへのコメントを許可すると、Google アカウントがなくても匿名でコメントできます。
Markdown を使用する
ドキュメントは GitHub に保存され、GitHub の Markdown 形式（仕様）を使用します。
PR を作成して既存のドキュメントを更新します。大幅な変更は ドキュメント審査担当者によって審査されます些細な変更（入力ミス、フォーマットなど） 誰でも承認できます。
審査担当者のワークフロー
レビュー担当者は、設計ドキュメントのコメント、レビュー、承認を行います。
審査担当者の一般的な責任
設計ドキュメントの審査、必要に応じた追加情報の要求、審査プロセスに合格した設計の承認が担当者の役割です。
新しい提案を受け取ったとき
- ドキュメントを簡単に確認します。
- 重要な情報が不足している場合や、設計がプロジェクトの目標に合致していない場合は、コメントを入力します。
- 追加の審査担当者を提案する。
- 審査の準備ができたら、PR を承認します。
審査プロセス中
- 問題がある問題や明確化が必要な問題について、設計担当者と対話します。
- 必要に応じて、設計に精通している審査以外のユーザーからのコメントを募集します。
- 承認の前提条件として、投稿者が対応する必要があるコメントを決定します。
- プロポーザルの現在の状態に満足している場合は、ディスカッション スレッドに「LGTM」（Looks Good To Me）と記入します。
すべての設計レビュー リクエストにこのプロセスに沿って対応します。Bazel に影響する設計が設計インデックスにない場合は、承認しないでください。
リード審査担当者の責任
実装の可否の判断はお客様の責任で行っていただく必要があります 修正することもできますこれができない場合は、 適切なデリゲート（PR をデリゲートに再割り当て）するか、バグを Bazel マネージャーによる追加処理。
審査プロセス中
- コメントと設計の反復プロセスが建設的に進むようにします。
- 承認する前に、他の審査担当者の懸念が解消されていることを確認します。
すべての審査担当者による承認後
- メーリング リストです。
- PR でステータスが更新されていることを確認します。
- 提案の作成者が送信した PR を承認する。
デザインの不承認
- PR 作成者が PR を送信していることを確認する。PR を送ってください
- PR がドキュメントのステータスを更新します。
- ドキュメントにコメントを追加して、現在の状態で設計を承認できない理由を説明し、次のステップ（「無効な前提条件を見直して再送信」など）を概説します。