pr-writing

编写、更新或评估 Pull Request 的标题和正文,让评审者理解实际行为变化、设计理由与验证边界。在准备 PR 文案或检查 PR 说明质量时使用。

SKILL.md

GitHub

PR Writing

让首次接触这次变更的评审者理解它解决什么问题、如何影响使用者,以及哪些地方需要重点审阅。

先确定说明对象

  • 读取适用的 AGENTS.md、CONTRIBUTING.md 和 PR 模板。遵守仓库的格式、语言与交付规则;未指定语言时,标题用英文,正文用中文。
  • 确认 PR 的目标分支与当前 head,以完整分支差异确定说明范围,结合现有 PR 文案、提交消息和关联 issue 理解背景。
  • 对堆叠 PR,区分本次新增变化与父分支已有变化。描述远端 PR 当前内容时,以远端 head 为准;本地待提交的改动单独标明。
  • 用已读取的代码、记录和明确背景支撑动机、验证结果与兼容性说明。信息有限时,说明已查看的范围和待核实事项。

默认输出规范

仓库已有约定时沿用其规范;其余情况按下面的标题规则和正文结构组织。

标题

使用 type(scope): concrete change。前缀中的 type 和 scope 用小写,描述概括当前整份变更的主要结果。

  • type 按主要结果选择:feat 新增能力、fix 修复缺陷、refactor 重构、perf 性能优化、docs 文档、test 测试、build 构建或依赖、ci 持续集成、chore 其他维护、revert 回退。
  • scope 使用受影响的模块或能力名称,例如 auth、catalog。当范围已由描述清楚表达,或变更跨越多个模块时,可省略 scope。
  • 描述默认使用英文,以小写的动词原形开头,写清具体对象和结果。专有名称和标识符保留原本的大小写,例如 API、GitHub;保持单行,句末省略句号。
  • 破坏兼容性的变更,在 type 或 scope 后加 !,并在正文交代影响和迁移方式。

例如:feat(auth): add passkey login、fix(catalog): preserve metadata during retries、docs: clarify local setup。

正文

默认使用“背景/主要改动/验证”三节。将模板中的提示替换为本次变更的事实,按实际内容取舍条目。

## 背景

[当前问题或缺口,以及本次变更要达成的结果。]

## 主要改动

- [具体行为变化及对使用者的影响。]
- [有助于评审的设计选择、理由与取舍。]

## 验证

- [已执行的检查:覆盖范围、环境与实际结果。]
- [尚未验证的范围及原因,必要时补充后续验证方式。]

写清变化与理由

开头交代原来的行为或缺口,再说明这次产生的具体结果。涉及多处实现时,按能力、行为或责任划分组织内容,把相关文件的改动汇总成评审者关心的行为变化。涉及兼容性或关键契约时,同时说明需要保持的行为。

有重要设计选择时,说明选择了什么、为何适合当前约束,以及相关代价或保留风险。方案比较聚焦实际考虑过、且有助于评审的选项。

术语应帮助评审者定位问题。例如描述并发控制时,说明它保护的行为或约束,再补充实现术语。把失败、取消、重试和恢复行为放在相关设计说明中,把这些行为的测试覆盖情况放在验证部分。

按变更规模组织

  • 小改动可以用一小段交代问题、结果与必要验证,保留仓库模板要求的栏目。
  • 常规功能或缺陷修复使用上述三节;复杂变更可按评审需要增加分节。
  • 涉及 API、数据格式、权限或存储契约变化时,说明受影响的使用方、兼容性与必要迁移。
  • 跨模块变更可提供简短的评审顺序。图示、前后对比和示例只在能降低理解成本时加入。
  • 有可见 UI 变化时,尽量在 PR 正文中提供评审者可访问的前后截图,确保页面、状态、视口尺寸和数据可比。标注 Before/After、比较基线与当前评审 head;桌面和移动端表现有实质差异时分别覆盖。 截图随最终实现更新,发布前遮去敏感信息。缺少真实基线或可供评审者访问的截图时,说明限制,只展示实际取得的证据。

让验证结论可判断

保留影响评审判断的证据:覆盖了什么行为、使用什么测试环境、结果如何,以及哪些范围仍未验证。例如,应区分模拟服务测试与真实服务互通。

引用实际执行记录或当前 CI 状态,分别表述已通过、失败、进行中、明确跳过和尚未运行;跳过时说明原因。让每项结论对应证据实际覆盖的范围,并将后续验证计划单独列出。将已解决的问题与已接受但仍存在的风险分开说明。

PR 正文概括代码变更、设计理由与关键验证结论。任务历史、重要进展和操作证据留在 issue 或指定任务记录,详细日志与运行产物保存在任务目录。任务同时有 issue 和 PR 时,在两处互相链接,避免重复整份记录。仅在精确命令有助于复现问题或验证特殊行为时保留命令。

更新与交付

  • 实现范围或设计发生实质变化后,重新检查整份标题和正文,整合成对最终结果的连贯说明。
  • issue 引用必须有可核对的来源。确实解决并应关闭的问题使用 Closes,仅关联背景使用 Refs。
  • 评估说明质量时,给出总体判断和重要的可执行建议,并明确评价覆盖的范围。涉及实现正确性的结论,以相应的代码审查和验证证据为依据。
  • 按当前任务约定交付文案或评价。执行提交代码、推送、发布、修改远端 PR 或合并等操作前,核对该操作是否在授权范围内;已有明确授权时直接执行。
  • 获准发布或更新后,回读远端标题、正文、base/head 和附件,确认渲染正确且内容对应当前变更。