pr-description

PR の説明

プロダクトを知っているものの、これまでの作業を追っておらず、ほかのタスクの合間に読むチームメイトに向けて書きます。ざっと一読しただけで、何が変わったのか、何を確認すべきかがわかるようにしてください。正確でも、説明が長くて詰め込まれていると読まれません。

実際の差分と、問題や変更後の動作、レビュー時のリスクを把握できるだけの背景を確認してください。動機をでっち上げたり、実施していない検証を実施したと主張したりしないでください。

まず視覚的な情報を

言葉よりも早く変更の証拠を伝えるものを、最初の見出しより上に置きます。

• 目に見える変更には、pr-screenshot-comparison で実際のプロダクトの変更前後の画像を用意します。シードデータまたはテストデータを使って撮影し、顧客名や連絡先情報が写らないようにトリミングしてください。撮影できない場合は、テストの項目でその旨を記載します。
• フロー、手順、または要素間のつながりの変更には、GitHub でレンダリングされる Mermaid 図を用意します。2文では伝えられない関係を示す場合に限り、図を作成してください。
• それ以外の変更では、文章から始めます。証拠の選び方では、録画、コマンド出力、データの形について説明しています。

簡潔な文章

• 変更の規模に合わせて文章量を調整します。 変更点が1つか2つなら、2～4文にします。独立した変更点が3つ以上ある場合は、箇条書きを使います。リポジトリに PR テンプレートの見出しがある場合は、それを使います。テストも含め、自分で書く文章は約200語以内にしてください。テンプレートのチェックリストなど、必須のセクションはこの語数に含みません。上限を超えたら、まず理由を削り、次に重要度の低い変更点を削ります。
• チームがプロダクトについて使う言葉で、ユーザーに見える変化を説明します。 画面、機能、顧客の状況について書きます。「コンポーネント名」ではなく「Team Chat のメッセージ入力欄」と書き、値を記録するフィールド名ではなく「担当者が Eve をオフにした」と書きます。レビュアーが対応する必要のある箇所に限り、コードの名前を出します。コードの仕組みは、執筆者向けのインライン注記で説明してください。
• すべての文で、影響、リスク、または確認事項を伝えます。 当てはまる範囲で、次の順に説明してください。何が問題だったか、変更によって何ができるようになるか、マージ後にほかに何が変わるか、レビュアーが何を確認すべきか、読者が含まれると思い込みそうなもののうち、この PR に含まれないものは何か。
• 結論の1行だけを太字にするか、何も太字にしません。
• テストには、手作業で確認したことと、確認していないことを記載します。 CI の結果はすでに PR に表示されています。
• 修正するときは、本文全体を書き直します。 誤った行は、新たな発見のたびにセクションを追加するのではなく、正しい内容に置き換えてください。

ドキュメント、ダッシュボードのクエリ、ソースコードの該当行など、根拠となる情報は、それを裏付ける文からリンクしてください。今回の変更ですでに実施した検証を再利用し、主張に影響する重大な不足があれば、その主張のそばに記載してください。

事前知識のない読者による確認

公開する前に、説明文だけを、ほかの背景情報を持たない読者に渡します。何が変わったのか、何を確認すべきか、作者に尋ねる必要がある用語は何かを聞いてください。回答に誤りがある場合や、答えるのに2文を超える場合は書き直します。コード由来でプロダクト上の用語ではないと指摘された用語も、書き直してください。その後、もう一度確認します。ツールや担当者の名前など、チームが日常的に使う用語はそのままでかまいません。別の読者に文章を渡す方法がない場合は、この手順を省略し、引き継ぎ時にその旨を伝えてください。

例

チャットエディターの8行の修正。コピーして使う文章ではありません。

[before and after image]

## What and why

Fixes PAD-2336.

**Starting a list in the Team Chat message box left the placeholder showing behind the bullet.** The placeholder now hides once a list or quote starts, and comes back when it's removed.

The post edit form and the recon notes box use the same editor, so they get the fix too.

## Tests

- Checked by hand in Team Chat: typing `- `, `1. ` and `> `, the list button, and backspacing out of a list.
- Not checked by hand in the post edit form or the recon notes box.
- No automated test added.

公開

スクリーンショットを添付する前に確認し、任意の選択肢への回答待ちの間も、許可された PR 作業を続けてください。

実際の複数行テキストをファイルに保存し、gh pr create --body-file または gh pr edit --body-file を使って公開してください。その後、保存した本文の生テキストを再度読み込み、意図したテキストになっていることを確認してください。

既存または新規の画像や動画を添付する場合は、添付ファイルのリンクを読んでください。元の永続的なアップロード URL を保持し、公開前と取得した本文の生テキストで公開後にチェッカーを実行し、レンダリングされた PR を確認してください。プレビューに成功しただけでは、URL の永続性は確認できません。PR のスクリーンショットを Git に含めないでください。また、作成者の許可がある場合にのみアップロードしてください。継続的な許可も有効です。

作成者によるセルフレビューのメモは、別個の任意のワークフローであり、pr-self-review を使用します。説明文を公開しても、チームメイトへのレビューコメントや返信が許可されたことにはなりません。