ユーザー向けの機能を追加、変更、削除する場合や、 重要なアーキテクチャの変更が伴う場合は、設計を記述する必要があります。 変更を提出する前に、その内容を確認し、審査を受けます。
重要な変更の例を次に示します。
- ネイティブ ビルドルールの追加と削除
- ネイティブ ルールの互換性を破る変更
- ネイティブ ビルドルール セマンティクスの変更により、より多くの 適用できます。
- Bazel のルール定義 API の変更
- Bazel が他のシステムへの接続に使用する API の変更
- Starlark の言語、セマンティクス、API の変更
- Bazel のパフォーマンスやメモリに広範囲に影響する可能性のある変更 （良いか悪いか）
- 広く使用されている内部 API の変更
- フラグとコマンドライン インターフェースの変更。
デザイン レビューを行う理由
設計ドキュメントを作成するときは、他の Bazel デベロッパーと調整できます Bazel のコアチームからアドバイスを求めることができます。たとえばプロポーザルに追加され BUILD、WORKSPACE、または bzl ファイルの場合は、レビュー担当者として Starlark チームを追加します。 次の理由により、設計ドキュメントは提出前に審査されます。
- Bazel は非常に複雑なシステムです。一見すると無害に見えるローカル変更が 深刻な影響をもたらしています
- チームにはユーザーから多くの機能リクエストが寄せられています。このようなリクエストは 技術的な実現可能性だけでなく、 リクエストできます
- 多くの場合、Bazel の機能はコアチーム外のユーザーが実装しています。 このようなコントリビューターは、Bazel に関するさまざまなレベルの専門知識を持っています。
- Bazel チーム自体の専門知識のレベルはさまざまです。チームメンバーが 1 人もいない Bazel のあらゆる側面をしっかり理解しています。
- Bazel の変更では、下位互換性を確保し、互換性の問題を回避する必要があります。 できます。
Bazel の設計レビュー ポリシーは、次のような可能性を最大化するのに役立ちます。
- すべての機能リクエストに対して、ベースラインレベルの精査が行われます。
- デザインについて検討してから 一部の実装では機能しない場合があります
使用を開始するには、 Bazel 提案リポジトリ。 設計は開発中のため、実装の詳細は今後変更される可能性があります あります公開された設計ドキュメントには、初期設計が記録されています。 設計の実装に伴う継続的な変更ではありません。常に 現在の Bazel 機能の説明をご覧ください。
投稿者のワークフロー
コントリビューターは、設計ドキュメントの作成、pull リクエスト、 審査担当者をリクエストできます
設計ドキュメントを作成する
すべての設計ドキュメントには、以下を含むヘッダーが必要です。
- 著者
- 前回の大きな変更日
- 1 人（1 人のみ）を含む審査担当者のリスト リード レビュアー
- 現在のステータス（下書き、審査中、承認済み、不承認、 実装中、実装）
- ディスカッション スレッドへのリンク（お知らせの後に追加）
ドキュメントは、誰でも読み取れる Google ドキュメントとして作成することもできます。 マークダウンを使用します。次をご覧ください: Markdown と Google ドキュメントの比較
ユーザーに見える影響のある提案には、 下位互換性への影響（および必要に応じてロールアウト計画）
pull リクエストを作成する
ドキュメントを追加する pull リクエスト（PR）を作成して設計ドキュメントを共有する デザイン インデックス。追加 PR へのマークダウン ファイルまたはドキュメントのリンクを記載してください。
可能であれば、リード審査担当者を選定します。 他のクチコミ投稿者を CC に含めます。リードレビュアーを選ばない場合は、Bazel 管理者が PR に割り当てます。
PR を作成したら、審査担当者は 説明します。たとえば、リードレビュアーが追加のレビュアーを提案したり、 不足している情報を指摘できますリード審査担当者が PR を承認するのは 審査プロセスを開始できますその提案が完璧というわけではない 承認される可能性がある。そのプロポーザルには 取引に必要な 十分な情報が ディスカッションを開始できます。
新しい提案を発表する
お知らせの送信先 bazel-dev が PR を提出します。
他のグループ（例: bazel-discuss、 Bazel エンドユーザーからフィードバックを得ることもできます）。
レビュー担当者と繰り返し行う
関心のあるユーザーなら誰でも提案にコメントできます。質問に答えるよう努める 提案を明確にして懸念事項に対処します。
ディスカッションはお知らせスレッドで行う必要があります。提案が Google ドキュメントでは、コメントの代わりにコメントを使用することもできます（ただし、匿名のコメントは 許可されています）。
ステータスを更新する
新しい PR を作成して提案のステータスを更新する（イテレーションが できます。PR を同じリード審査担当者に送り、他の審査担当者を CC に含める。
提案を正式に承認するには、リード審査担当者がその後 PR を承認します。 他の審査担当者も決定内容に合意します
最初の発表から できます。これにより、ユーザーはドキュメントを読むのに十分な時間を確保し、 共有することです
実装は、提案の承認前（ テストになりますただし、変更を送信することはできません。 おすすめします
リードレビュアーの選定
リード審査担当者は、次のようなドメイン エキスパートである必要があります。
- 関連するサブシステムについて熟知している
- 客観的であり、建設的なフィードバックを提供できること
- プロセスを主導するために審査期間全体を通して利用可能
さまざまなチームの連絡先を確認することを検討します。 ラベル。
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 がドキュメントのステータスを更新します。
- デザインが承認されない理由を説明するコメントをドキュメントに追加します。 現在の状態、および次のステップの概要を記載します（例: 「無効な 再送信してください」）。