write-pr-description

write-pr-description

プルリクエストの説明文の役割は、差分だけでは伝わらない情報をレビュアーに伝えることです。

差分には、すでに何が変わったかが示されています。説明文では、なぜ変更したのか、何に影響するのか、どのような判断を経たのか、そして執筆者がどこに注目してほしいのかを伝えます。以下の内容はすべて、ここから導かれます。このルールが特定のレビュアーのニーズと相反する場合は、レビュアーのニーズを優先してください。

create-pr ではプルリクエストを作成する手順を扱います。このスキルでは、本文に何を書くかを扱います。

1. 下書きを始める前に事実を集める

通常は自分で作業しているため、ほとんどの情報はすでに把握しているはずです。自分が書いていないブランチや、引き継いだばかりのプルリクエストについて説明する場合は、ここから始めてください。

# From a checkout of the branch
git --no-pager log <base>..HEAD            # commit bodies first, they carry the why
git --no-pager diff <base>...HEAD --stat

# From a PR number, with no local branch
gh pr view <n> --repo <owner/repo> --json title,commits,files,baseRefName
gh pr diff <n> --repo <owner/repo>

差分を見る前に、コミット本文を読んでください。通常、変更の動機を知るうえで最も有益な情報源です。そのうえで、主張の内容を確認してください。「このファイルにある既存のパターンに沿っています」というコミットメッセージはコードについての主張であり、誤っていることもよくあります。確認していない主張をそのまま伝えてはいけません。

推論ではなく、実際に確認してください。確認すべき項目は、手軽で具体的です。

• 変更によって削除された内容を読んでください。問題を修正するための変更であれば、削除されたコードに不具合が表れていることがよくあります。
• 推測するのではなく、あるものの意味をシステムに確認してください。ロールの権限セットなら gcloud iam roles describe、リソースのフィールドならプロバイダーや API スキーマ、マーカーの動作ならパーサーを確認します。
• フラグが有効か無効かを主張する前に、環境ファイル全体でそのフラグを grep してください。
• コメントやコミットメッセージで示されているファイルを開き、参照先が主張どおりの内容か確認してください。

このような確認を一度行うだけで、説明文の中で最も優れた一文が生まれることがあります。

差分だけではレビュアーに伝わらない情報を集めてください。

• 変更の動機。変更しない場合、何が壊れるのか、どのようなコストが生じるのか、何ができないままなのか。
• 関連する issue、仕様書、設計ドキュメント、およびブランチでコミットされた仕様ファイル。
• 実質的な代替案があった判断と、その代替案を採用しなかった理由。
• 影響範囲。変更したファイル以外で、何が壊れる可能性があるのか。
• 実行した検証と、その結果。
• 不確かな点。

2. リポジトリのテンプレートに従う

リポジトリに PR テンプレートがあるか確認します。複数ある場合は、変更内容に合ったものを選びます。テンプレートはリポジトリごとに異なるため、前回の PR の形式を流用せず、毎回確認してください。

テンプレート自体の指示は、このスキルの指示より優先されます。「該当しない場合はこのセクションを削除」と書かれたテンプレートは、このリポジトリのレビュアーが何を求めているかを示しています。その指示に従ってください。以下のガイダンスは、テンプレートに指示がない場合に適用されます。

• 見出しとその文言、順序を維持します。レビュアーもツールも、それらを基準に確認します。
• 各見出しの下に、自分の言葉で、すべてのセクションに回答します。テンプレートの質問文、説明用リンク、例はそのまま転載しないでください。4つの確認セクションがあるテンプレートで、4回「いいえ」と答えるだけでも、200語を費やしかねません。
• 該当しないセクションは、削除したり空欄にしたりせず、検討したことが伝わる一文で示します（「新しいテーブルはありません」など）。
• チェックボックスには、記載された内容が真の場合にのみチェックを入れます。そうでなければチェックを入れず、同じ行に簡潔な理由を書きます。チェックボックスを削除したり、但し書きを添えてチェックしたり、チェックボックス自体の文言を読者に繰り返したりしないでください。
• 機械が読み取る内容（変更履歴マーカー、成果物またはメディアのマーカー、課題リンクキーなど）を維持します。テンプレートの指定位置で、そのマーカーが有効になっているか確認してください。テンプレートによっては、パーサーが除去する HTML コメントの中にマーカーが記載されており、そのまま残してもマーカーが無視されることがあります。パーサーまたはマージ済みの PR で確認してください。
• 指示用の HTML コメントは、回答したら削除できます。

テンプレートがない場合は、テンプレートと同じ構成になる次の形式を使います。

1. 見出しを付けず、ステップ 3 の冒頭の段落から始めます。「何を」と「なぜ」の両方を伝えるため、独立した Why セクションは不要です。
2. ステップ 4 で必要とされる場合は、## Review guide
3. ## What changed
4. ## Validation

小さな変更では、この構成を簡略化します。1行だけのセクションに見出しを付けるのは、ステップ 4 が警告する形式的な手続きと同じです。そのようなセクションは省き、冒頭の段落に内容を含めます。

3. 本文を書く

変更内容とその理由を、1〜3文で冒頭に記します。最初の段落だけを読んだレビュアーにも、自分が適切なレビュアーかどうかがわかるようにします。

リポジトリにテンプレートがある場合、この段落は最初の内容セクション（名称は問いません）の中に記載します。テンプレートの最初の見出しより前に導入文を追加したり、セクション内でもう一度繰り返したりしないでください。

続けて、変更の要点を説明します。

• コードから自明でない場合に限り、仕組みを説明します。新しい抽象化、複数箇所にまたがる不変条件、通常とは異なる制御フローには段落での説明が必要です。フィールド名の変更には不要です。
• メインの変更に伴う副作用も含め、動作の変更を明示します。他の人に影響するのは、こうした変更です。権限を変更した場合は、その方向性を示します。以前は許可されなかった何が許可されるようになり、以前は拒否されていた何が拒否されるようになったのかを記載します。
• 採用した代替案と、採用しなかった代替案を記録します。これは多くの説明において最も価値の高い情報であり、差分からは復元できません。現実的な代替案がなかった場合は、決定事項をそのまま明記します。項目を埋めるために、代替案を捏造しないでください。
• ユーザーに見える変更には、視覚的な証拠を含めます（スクリーンショット、または変更の場合は変更前と変更後の画像）。実在するキャプチャのみを参照してください。
• 課題、仕様、会話へのリンクは一度だけ記載します。リンク先がない場合は、リポジトリからテンプレートのセクションやコントリビューションガイドを通じて求められている場合に限り、その旨を記載します。課題を使わないリポジトリで「関連する課題はありません」と告げるのは、情報ではなく、リンターへの対応にすぎません。空欄を埋めるために、もっともらしい課題 ID を捏造しないでください。誤ったリンクは、リンクがないことより大きな問題になります。

検証

通常はあなたが作業を実行したのだから、それを報告してください。実行したコマンドと、それが示した内容です。

実行していない場合、または一部しか実行していない場合は、正直に次の形で述べます。複数が同時に当てはまることもあります。ある事実は自分で検証しつつ、残りは CI の結果を待っている、という状況はありえます。

• 何も実行していない。 そのまま明言し、レビュアーまたは CI が実行すべきコマンドを挙げてください。
• CI が結果を出す場合。チェックに資格情報や、使うべきでない環境が必要だからです。ジョブ名を挙げ、期待される表示内容を述べ、それは観察ではなく期待であると明示してください。「destroy が 1 件、create が 1 件、それ以外は何もないはず」と書けば、レビュアーはその実行結果と照らし合わせて確認できます。これは沈黙よりも有用です。あなたが見た出力だと誤読されないような言い回しにしてください。
• ブランチがテストを追加しているが、実行の記録がない。 テストは追加済みで未実行だと述べてください。そうすれば、テスト一覧を合格の証拠と読む人はいません。
• 実行できなかった場合。デバイス、資格情報、または環境がなかったためです。その旨を述べ、レビュアーに依頼するチェックとして挙げてください。これはあなたが省略したものには当てはまりません。実行できたのであれば、実行してください。
• 他の誰かが結果を記録した場合。たとえば以前のコミットに検証が記されているケースです。出典を明示するか、触れないでください。自分の観察として言い直してはいけません。

どれに当てはまる場合でも、それぞれ一度だけ述べてください。「これは実行していません」を 3 つのセクションで繰り返すと、責任逃れのように読まれ、代わりに何を実行すべきかを述べた一行が埋もれてしまいます。

意図を結果であるかのように書いてはいけません。

文章

ASD-STE100 を基準にしてください。能動態、1 文につき 1 トピック、文はおよそ 25 語以内、単純な時制、説明全体を通じて 1 概念につき 1 用語です。コード識別子、コマンドライン、定着したリポジトリの専門用語は技術名です。そのままにしてください。ルールと例外については references/plain-language.md を参照してください。

4. 必要とされる場合はレビューガイダンスを追加する

読む順序が自明でない場合、特に注意を向けてほしい箇所がある場合、またはその変更が触れるファイルのはるか先まで壊しうる場合には、レビューガイドを追加してください。有能なレビュアーが指示されなくてもどこを見ればよいか分かる場合は、省略してください。

要約のすぐ後という高い位置に置いてください。レビュアーが、どこから始めればよいかを見つけるためにコンプライアンスのチェックリストをスクロールして通り過ぎなければならないようではいけません。テンプレートが用意していない場合、## Review guide は妥当な既定の見出しです。

小さな PR では、ガイダンスはセクションではなく 1、2 文です。それに対して見出しを立てるのではなく、冒頭に織り込んでください。2 段落に見出しを付けるのは形式的な儀礼であり、6 ファイルの読む順序も同様です。

レビューガイドには、次の一部または全部を含めます。

• 推奨する読む順序。順序が重要になるほど大きな PR の場合。
• 注目領域: あなたが確信を持てない点、セキュリティに関わる表面、意味のある代替案を伴う決定、そして曖昧さが genuine な一方通行の扉。

有能なエンジニアに向けて書いてください。コードと未解決の問いを指し示し、コードのレビュー方法を説明してはいけません。冒頭に、そのどのセクションが必要かの短い地図がある references/review-guide.md を参照してください。

5. 削る

下書きは長くなりがちですが、冗長さの原因はほとんどの場合、考察そのものではありません。冗長さがたまるのは、義務的に感じる部分、つまりチェックリストへの回答、テストの一覧、すでに述べた内容の繰り返しです。こうした部分は最も削りやすいので、この作業は手軽で、毎回行う価値があります。

削り始める前に、本文全体のおおよその目安を確認してください。

• 動作に変更のない、テストのみの変更、設定変更、または機械的な変更：短い段落。
• リスクの実質的な範囲がある小規模な変更：数百語程度。そのほとんどを、差分ではなくリスクの説明に充てます。
• 対象を絞った修正や機能追加：400〜500語。
• 利用側がある新しい仕組み：1,000語未満。
• 非常に大規模な変更や基盤となる変更：1,000語程度。増えた分の大半は、読む順序と重点箇所の説明に充てます。

これらは目安であり、上限ではありません。目安を超えたら、以下のリストをより厳しく確認してください。ただし、決定事項を削る理由にはなりません。

次に、各段落について、レビュー担当者がどのような判断を下すのに役立つのかを明確にしてください。言えない場合は削除します。よくある削除候補は次のとおりです。

• 差分を見ればすぐにわかること。「ハッシュスクロールのロジックを汎用化した」「フィールド名を変更した」といった説明、変更行ごとの箇条書き、ロックファイルの内容の言い換えなどです。意図しないように見えるものは例外です。たとえば、名前と紐付け先が一致していない場合などです。レビュー担当者はそれを目にできますが、誤りだとは判断できないため、説明を残します。
• この差分で追加したコメントの言い換え。レビュー担当者は、そのコメントを該当箇所ですぐに読めます。
• 追加したテストの一覧。カバーされていない内容と、変更のおよそどの程度がテストされているかを示してください。テスト関数名の羅列は、特に結果の記載がなければ、かさ増しに見えます。
• 標準的なツールの動作説明。Terraform が名前変更されたリソースを置き換える仕組み、テストマクロがポーリングする仕組み、React のエフェクトが実行されるタイミング、ライブラリが子プロセスを起動する仕組みなどです。説明するのはこの変更であり、レビュー担当者が使うツールではありません。
• 同じ事実の繰り返し。数えてみてください。「関連する issue がない」と「何も実行していない」は、それぞれ一か所にだけ記載します。二度述べる価値のある事実は、たいてい最初の述べ方に問題があります。
• 説明の別の箇所を指し示すだけの文。同じページ内で相互参照が必要なら、内容の配置が適切ではありません。
• 説明文そのものについて述べる文。「この変更は影響範囲が広いため、レビューガイドを付けています」などです。説明する代わりに、ガイドを書いてください。
• コミットのトレーラー。Co-Authored-By は PR の本文ではなく、コミットに記載します。

大幅に削る場合でも、動機、動作の変更、決定事項と却下した代替案、未解決の疑問点、影響範囲は残してください。説明文を書く理由はこれらにあります。何かを削る必要があるなら、決定事項より先に仕組みの説明を削ってください。

6. セルフチェック

• 最初の段落を読めば、レビュー担当者はこの PR が自分の担当かどうか判断できますか？
• テストについて述べる内容はすべて、実際に実行したことを説明していますか？ それとも、実行していないことを明確に述べていますか？
• コミットメッセージから引き継いだ事実の記述をすべて確認しましたか？
• 削ったことで、決定事項、却下した代替案、未解決の疑問点が失われましたか？ 圧縮する際に最初に削られがちで、最後まで残すべきなのはこれらです。戻してください。
• 説明文は、たどった経緯ではなく、現在のブランチの状態を反映していますか？
• レビュー担当者向けの案内がある場合、上部にありますか？

アンチパターン

ブランチ自身の履歴を説明すること。 最もよくある失敗です。「この PR には以前ユニットテストが含まれていましたが、レビューのフィードバックを受けて削除しました」や「上の説明は誇張されていたため、修正しました」のような文は、レビュー担当者が読んでいる差分には存在しない変遷を説明しています。レビュー担当者が見るのは、ベースに対するひとつの状態です。その状態を説明してください。

このルールを適用しても残る点に注目してください。通常、理由は依然として重要であり、変遷の部分だけを省きます。「テストはマッチアームを再確認するだけだったため削除しました」は、「このレイヤーのテストはマッチアームを再確認するだけになるため、ユニットテストはありません」となります。

ブランチの長さにかかわらず、これは当てはまります。コミットが30個あるブランチでも、レビュー担当者にはベースに対するひとつの状態として届きます。

差分の言い換え。 ファイルごとの一覧は、情報を含まない長文を書くときの定番です。

検証されていない主張。内容を問いません。 テストに関する誇張した主張（「完全にテスト済み」「リグレッションなし」など）がよく見られますが、仕組みに関する自信たっぷりの誤った主張は、レビュー担当者が確認する可能性が低いため、より危険です。あるロールで何が許可されるのか、フラグで何が制御されるのか、関数が何を保証するのかを主張する前に、検証してください。

自分の成果を採点すること。 「包括的」「堅牢」「クリーン」「適切に」など。信頼性を損なうだけの水増しです。

レビュー担当者に説教すること。 「エッジケースを確認し、エラー処理が正しいことを確かめてください」。有能なレビュー担当者なら、すでにそうしています。また、その一文によって、あなたにしか示せない具体的な確認箇所が埋もれてしまいます。

古い説明を残すこと。 手直しやフォースプッシュの後は、現在のブランチを説明する内容に本文を書き直してください。末尾に改訂履歴を追加してはいけません。