编写审阅者可用的 PR 描述
目标:让审阅者在两分钟内决定要看什么,让未来的读者理解变更存在的原因。
收集
- 找到基础分支,然后运行
git log --oneline <base>..HEAD和git diff --stat <base>...HEAD,再阅读 diff。 - 寻找变更原因:提交或分支名称中关联的问题或工单编号、用户请求、diff 中添加的注释。如果原因不在以上任何地方,请询问用户;切勿虚构动机。
- 检查测试情况:diff 中的测试文件,以及用户运行过的命令。如果测试未运行,请如实说明。
- 查找是否存在
.github/pull_request_template.md或PULL_REQUEST_TEMPLATE。如果有,则填写该模板,而不是使用下面的结构。
结构
<Title: 祈使语气,不超过 70 个字符,命名行为变更而非文件>
## Why
<问题或请求,1 到 3 句话。如有问题则链接它。>
## What changed
- <按领域分组的行为级别要点,不是文件列表。>
## How to review
- 从 <文件或领域> 开始;其余部分随之而来。
- 风险部分:<最容易出错的部分及其原因>。
- 有意未修改:<审阅者可能期望看到但不会发现的内容>。
## Testing
- <运行的确切命令及其结果。>
- <手动步骤及观察到的现象。如果适用,写明“未测试:...”>。
## Rollout / risk
<迁移、配置、功能标志、兼容性、回滚方式。仅在确实没有时才写“None”。>
规则
- 描述 diff 实际做了什么,而不是你希望它做什么。起草后重新阅读 diff,删除任何 diff 不支持的声明。
- 不要列出每个文件。但要列出行为变更、新配置、新依赖和删除的代码。
- 不要使用填充语(例如“此 PR 旨在……”)。除非仓库使用表情符号,否则不要使用表情符号。
- 截图或输出示例:说明在何处会有帮助;永远不要描述你未见过的截图。
- 将标题和正文放在代码块中输出,以便复制。除非被要求,否则不要运行
gh pr create。