pr-screenshots

PR のスクリーンショット

PR のスクリーンショットは QA の証拠です。それぞれのスクリーンショットには、実際の製品がある場所でどのように表示されるかが写っています。まだそのページを開いたことがないレビュアーにも変更点が分かるように、表示範囲を調整してください。

ステップ 1：場所をリストアップする

差分が影響する製品内の場所をすべてリストアップします。変更されたコンポーネントを表示する各ページ、ドロワー、モーダル、ウィジェットを、呼び出し元と利用箇所をたどって特定してください。次に、ローディング、エラー、空、ホバー、選択済み、メニューを開いた状態、展開、スクロール、狭いビューポート、ライトテーマやダークテーマなど、その変更が各場所に及ぼす状態を追加します。

画面を複数まとめて1行にしてはいけません。たとえば、「GridEditable（Discover、ダッシュボード、インサイト）」は3行に分けます。

ステップ 2：実際の製品からキャプチャする

ルール	詳細
実際のビルドのみ	「変更後」は PR ブランチ、「変更前」はベースブランチで実行中のアプリをスクリーンショットに撮ります。変更対象がそのストーリーである場合を除き、ストーリー、モックページ、PR 用に作成されたハーネスのスクリーンショットは撮影しないでください。
変更の注入禁止	変更を模倣するために CSS を注入したり、DOM を変更したりしてはいけません。API レスポンスのスタブ化は問題ありませんが、フロントエンドのコードは実際のコードを使ってください。
不足データの準備	どのアカウントにもないデータが状態の再現に必要な場合は、ローカル環境で作成します。シードデータの準備を試すまでは、その場所のスクリーンショット撮影は不可能だと報告してはいけません。試した後に撮影できなかった場合は、何が失敗したのかを正確に記載してください。
同じ表示範囲	状態の一方が縦に長い場合でも、ペアとなる両方のスクリーンショットで、同じ範囲を同じ寸法で撮影します。ユーザー自身のブラウザーウィンドウのサイズを変更するのではなく、ビューポートを固定してエミュレートしてください。
コンテキスト	対象を示す見出しやラベル、近くの行やコントロール、そして四辺に少し余白を残します。ホバー、フォーカス、メニューを開いた状態では、トリガーとオーバーレイが1つのフレームに収まるようにします。ページ内でのみ不具合の意味が分かる場合は、ページを広く表示してください。
空白帯をなくす	ブラウザーの枠、アプリのナビゲーション、変更の影響を受けない領域を切り取ります。全幅レイアウトでは、短いコンテンツの横に広い空白を残すのではなく、ビューポートを狭くしてください。

ステップ 3：マスキングして監査する

1. メールアドレス、ユーザー名、顧客名や組織名とスラッグ、ID、内部ホスト名などの非公開値のみをぼかします。browser.name → chrome のように、キー、ラベル、機密ではない値は読める状態に保ちます。
2. ぼかす前に各領域を塗りつぶし、ぼかしを元に戻せないようにします。黒や濃色のベタ塗りは使わず、テーブルや行全体をぼかしてはいけません。
3. アップロードする前にすべての画像に目を通し、認証情報が含まれていないか確認します。対象は、トークン、認証ヘッダー、Cookie、署名付き URL、シークレットキー、Webhook エンドポイントです。実際の情報漏えいは取り除いてください。公開されているクライアント DSN は情報漏えいとして扱わないでください。

ステップ 4：テーブルの形式を選ぶ

変更	形式
既存の UI の視覚的な変更	Changed テーブルと、差分の対象箇所のうち表示に変化がないものを示す Unchanged テーブル。
新しいページや機能	変更前・変更後の比較は不要です。変更後のスクリーンショットをいくつか掲載し、それぞれの前に短い説明文を付けます。新しい UI が複数の場所に表示される場合は、代わりに Location | Screenshot テーブルを使います。
プロトタイプのデザイン案やデザインオプションなど、変更前の状態がない複数の案	案ごとに 1 行の Treatment | Screenshot テーブル。
テーマによって異なる変更	各場所にライトとダークの行を追加します。たとえば Explore › Logs, dark のようにします。新しい UI の場合は、代わりに Light | Dark 列を使います。

変更前・変更後の各ペアをピクセル単位で比較します。アンチエイリアスのノイズを含め、目に見える差がないペアは Unchanged に移し、画像を 1 枚だけ掲載します。空になるテーブルは省略します。

**Changed**

| Location | Before | After |
| --- | --- | --- |
| Explore › Logs | ![Explore › Logs before](./shots/logs-before.png) | ![Explore › Logs after](./shots/logs-after.png) |
| Explore › Logs, loading | ![Explore › Logs, loading before](./shots/logs-loading-before.png) | ![Explore › Logs, loading after](./shots/logs-loading-after.png) |

**Unchanged**

| Location | Before & After |
| --- | --- |
| Trace view › Logs | ![Trace view › Logs](./shots/trace-logs.png) |

書式ルール：

• 1 列目には Location、案を示す場合は Treatment という名前を付けます。見出しを空欄にしてはいけません。
• 各場所は、読者がクリックしてたどる順序を › でつないだパンくずリストにし、その後にカンマと状態を記述します。例：Monitors › cron monitor details › Check-Ins, loading。
• 上記に示した列のみを使います。「What changed」列やメモ列を追加してはいけません。変更点はスクリーンショットで示します。
• 各画像の alt テキストには、Explore › Logs before のように、行と変更前・変更後のどちらかを明記します。
• テーブルには太字の **Changed** 行と **Unchanged** 行を付けます。スクリーンショットの撮影場所や撮影方法を説明する導入文は追加しないでください。
• gh --attach が Markdown の画像参照のみを書き換えるため、通常は Markdown テーブルを使います。セルをまたいで行を結合する必要がある場合に限り、HTML テーブルに切り替えます。たとえば 1 つの場所の下にライトとダークの行を並べる場合は、Location | Theme | Before | After とし、場所のセルに rowspan="2" を指定します。align 属性は追加しないでください。

ステップ 5：gh でアップロードする

gh pr create、gh pr edit、gh pr comment と、対応する gh issue コマンドは、--attach '<path>#<alt text>'（gh 2.99.0+）を受け付けます。gh がこのフラグを拒否した場合は、ユーザーにアップグレードを依頼してください。アセット用ブランチをプッシュしたり、画像をコミットしたり、ブラウザーのコメント欄からアップロードしたりしないでください。

相対パスの Markdown 画像参照を使って本文ファイルを作成し、同じパスを --attach に渡します。gh は各ファイルをアップロードし、対応する参照をアップロード先の URL に置き換えます。

gh pr edit 123 --body-file pr-body.md \
  --attach './shots/logs-before.png' --attach './shots/logs-after.png'

動作	詳細
パス	現在のディレクトリを基準に解決され、本文内の参照と完全に一致している必要があります。
参照されていない添付ファイル	 として本文の末尾に追加されます。
body フラグなし	gh pr edit --attach は既存の本文を保持し、画像を追加します。
HTML テーブル	<img src="./x.png"> は書き換えられません。先に添付し、追加された URL を <img> タグにコピーして、追加された行を削除してから、--body-file で最終的な本文を渡します。

ユーザーが編集した可能性のある本文を書き込む前に、もう一度取得して、最後に読み込んだバージョンと比較してください。ユーザーの文言とテーブルの編集を保持し、自分の行と URL だけを差し替え、本文の改行コードも維持してください。本文から画像を削除しても、アップロードしたファイルは削除されません。

ステップ 6：スクリーンショットを最新の状態に保つ

後続のコミットでスクリーンショットの内容が変わった場合は、該当するペアを撮り直し、どのペアを Changed と Unchanged に含めるかを再確認して、依頼を待たずに本文を更新してください。