pr-description

PR 描述

面向熟悉产品、但不了解这项工作，并且正忙着处理其他任务的队友来写。让他们快速读一遍就能知道改了什么、需要检查什么。描述再准确，如果写得太密，也没人会读。

查看实际差异和足够的上下文，弄清问题、变更后的行为以及评审风险。不要凭空编造动机，也不要声称做过实际上没有做的验证。

先展示效果

在第一条标题之前的顶部，先放能比文字更快展示变更的证据：

• 可见的变更要使用 pr-screenshot-comparison 提供实际产品的前后对比图。使用预置数据或测试数据进行截图，并裁掉客户姓名和联系方式。无法截图时，在测试部分说明。
• 流程、顺序或组件连接方式的变更要配上 Mermaid 图，GitHub 可以渲染。只有在图能展示两句话无法说明的关系时才绘制。
• 其他任何变更都从文字开始。证据选择介绍了录屏、命令输出和数据形状。

纯文本

• 根据变更的规模控制文字长度。 有一两个要点的变更写两到四句话。三个或更多独立要点时使用项目符号。仓库有 PR 模板标题时，使用这些标题。包括测试在内，自己撰写的文字控制在约 200 个词以内。模板中的清单和其他必需部分不计入。超出限制时，先删原因，再删最不重要的要点。
• 用团队描述产品时使用的说法，说明用户会看到什么： 屏幕、功能和客户场景。写“Team Chat 消息框”，而不是组件名称；写“某位客服关闭了 Eve”，而不是记录此操作的字段值。只有在评审者需要对代码采取行动时才提及代码。代码的工作原理放在作者的行内注释中解释。
• 每句话都要说明效果、风险或检查事项。 按以下顺序说明，视情况而定：出了什么问题、变更做了什么、合并后还有哪些行为会有所不同、评审者应检查什么，以及读者可能会以为本 PR 包含但实际上没有包含什么。
• 加粗一行重点，或者不加粗。
• 测试部分列出人工检查过的内容，以及未检查的内容。 CI 结果已显示在 PR 中。
• 修订时，重写整个正文。 用正确内容替换错误内容，不要每有新发现就追加一个新章节。

从支持相应说法的句子中添加证据链接，例如文档、仪表盘查询或源代码行。重用当前变更已有的验证结果，并在重要缺口旁说明它会限制哪些说法。

冷读

发布前，只把描述文本交给一位没有其他上下文的读者。问他们改了什么、要检查什么，以及哪些术语需要向作者询问。如果回答有误或超过两句话才能回答，就重写。代码术语被指出时，也要改写。团队日常使用的术语，例如工具和人员的名称，可以保留。没有办法交给独立读者时，跳过这一步，并在交接说明中注明。

示例

修复聊天编辑器中的一个 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。发布描述并不代表获准发表评审评论或回复队友。