pr-screenshots

PR 截图

PR 中的截图是 QA 证据。每张截图都展示了真实产品在某个位置的渲染效果，并且取景恰当，让从未打开过该页面的评审者也能看出发生了什么变化。

第 1 步：列出位置

列出 diff 涉及的产品中的每个位置：通过追踪调用方和使用方，找出渲染了变更组件的每个页面、抽屉、模态框或小组件。然后补充该变更在每个位置影响的状态，例如加载、错误、空状态、悬停、选中、菜单打开、展开、滚动、窄视口以及浅色或深色主题。

不要把多个界面归到同一行：例如，“GridEditable，如 Discover、dashboards 和 insights 中所示”应分为三行。

第 2 步：从真实产品中截取

规则	详情
仅使用真实构建	“变更后”截图取自 PR 分支上运行的应用，“变更前”截图取自基准分支。除非变更本身针对某个故事，否则绝不要截取故事、模拟页面或为 PR 构建的测试框架。
不得注入变更	绝不要注入 CSS 或修改 DOM 来模拟变更。可以替换 API 响应；前端代码必须是真实代码。
补充缺失数据	如果某个状态需要任何账号都没有的数据，请在本地环境中创建。在尝试补充数据之前，不要报告某个位置无法截图；如果尝试后仍无法截图，请准确说明失败原因。
取景一致	一组截图中的两张必须截取相同区域、使用相同尺寸，即使其中一个状态更高也是如此。请模拟固定视口，而不是调整用户自己的浏览器窗口大小。
保留上下文	保留用于标识对象的标题或标签、附近的行或控件，并在四周留出少许边距。对于悬停、聚焦或菜单打开状态，触发元素和浮层须同时出现在同一画面中。如果只有结合页面才能理解问题，请展示更多页面内容。
不留空白带	裁掉浏览器界面、应用导航栏以及变更未涉及的区域。对于全宽布局，应缩小视口，而不是在较短的内容旁留出宽阔的空白。

第 3 步：脱敏并审核

1. 仅模糊处理私密值：电子邮件、用户名、客户或组织名称及 slug、ID 和内部主机名。保留密钥、标签和非敏感值，使其清晰可读，例如 browser.name → chrome。
2. 模糊处理之前，先在每个区域上涂色，防止模糊效果被还原。绝不要使用纯黑色或深色方框，也不要将整张表或整行模糊处理。
3. 上传前逐张查看图片并检查凭据：令牌、身份验证标头、Cookie、签名 URL、密钥和 webhook 端点。删除真实泄露的信息。不要将公开的客户端 DSN 视为泄露信息。

第 4 步：选择表格形式

变更	形式
现有 UI 的视觉变更	使用 Changed 表格；对于差异检查涉及但渲染结果相同的位置，另用 Unchanged 表格。
新页面或功能	不做前后对比。提供几张「变更后」截图，每张前加一句简短说明。如果新 UI 出现在多个位置，则改用 Location | Screenshot 表格。
没有「变更前」的备选方案，例如原型样式或设计选项	使用 Treatment | Screenshot 表格，每种备选方案占一行。
按主题而异的变更	为每个位置添加浅色和深色两行，例如 Explore › Logs, dark。对于新 UI，则改用 Light | Dark 列。

对每组变更前后截图进行像素差异比较。若某组截图没有可见差异（包括抗锯齿噪点），则移至 Unchanged，并只保留一张图片。若表格为空，则省略该表格。

**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) |

格式规则：

• 第一列命名为 Location；备选方案则命名为 Treatment。表头不得留空。
• 每个位置都写成读者点击路径的 › 面包屑，然后加逗号和状态：Monitors › cron monitor details › Check-Ins, loading。
• 只能使用上文所示的列。不得添加「变更内容」或备注列；截图会展示变更。
• 使用粗体 **Changed** 和 **Unchanged** 行作为表格标题。不得添加说明截图拍摄位置或方式的引言。
• 默认使用 Markdown 表格，因为 gh --attach 只会重写 Markdown 图片引用。仅当单元格需要跨行时才改用 HTML 表格，例如同一位置下有浅色和深色两行（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'

行为	详情
路径	相对于当前目录解析，且必须与正文中的引用完全一致。
未引用的附件	会以  的形式追加到正文末尾。
未指定正文标志	gh pr edit --attach 会保留现有正文，并追加图片。
HTML 表格	<img src="./x.png"> 不会被改写。先附加图片，将追加的 URL 复制到 <img> 标签中，删除追加的行，然后使用 --body-file 写入最终正文。

在写入用户可能编辑过的正文之前，请重新获取正文，并与上次读取的版本进行比较。保留用户的措辞和表格编辑，只替换你负责的行和 URL，并保留正文的换行符格式。从正文中移除图片不会删除已上传的文件。

第 6 步：保持截图最新

如果后续提交更改了截图所展示的内容，请重新截取受影响的截图对，重新检查哪些截图对属于 Changed 和 Unchanged，并主动更新正文。