GitHub Pull Request 模板引导作者提交可复现信息

在 GitHub 仓库的默认分支中创建 .github/pull_request_template.md，以后贡献者新建 Pull Request 时，正文会自动带出这份模板。模板最值得收集的不是泛泛的“改了什么”，而是审核者能直接执行的复现步骤、实际结果、预期结果、测试证据、影响范围与回滚办法。

GitHub 官方文档：https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository

使用场景：把审核前的追问变成提交时的填写项

没有模板时，Pull Request 很容易只写“修复登录问题”“优化查询”之类的结论。审核者仍然不知道问题出现在哪个环境、如何触发、修改前后分别是什么结果，也无法判断作者是否覆盖了回归测试。

一份实用模板应该让作者在提交时回答六类问题：

1. 变更说明：为什么改，以及改动解决了什么问题；
2. 复现步骤：审核者可以独立执行的最小步骤；
3. 实际与预期结果：改动前发生什么，正确结果应该是什么；
4. 验证信息：测试环境、测试命令和脱敏后的证据；
5. 风险与回滚：影响范围、兼容性与回退方式；
6. 提交前检查：关联 Issue、测试状态和敏感信息检查。

版本和入口：模板必须先进入默认分支

GitHub 支持把单个 Pull Request 模板放在仓库根目录、docs/ 或 .github/ 目录。本文使用 .github/pull_request_template.md，这样仓库根目录更整洁，也便于把协作配置集中在 .github 下。

模板只有存在于默认分支时，创建 Pull Request 才能稳定使用。若当前改动先进入 docs/add-pr-template 分支，需要先完成该分支对应的 Pull Request 并合并到 main，然后再用另一个新分支验证自动填充。

步骤一：从 Code 页进入新建文件入口

1. 打开目标仓库主页，确认当前位于 Code 标签。
2. 在文件列表右上方单击 Add file。
3. 在展开菜单中选择 Create new file。

如果看不到 Add file，先检查当前账号是否对仓库有写入权限。只读成员可以在 Fork 中创建文件，但最终仍需通过 Pull Request 把模板合并到上游默认分支。

步骤二：创建模板文件并写入填写项

在文件名输入框中直接填写 .github/pull_request_template.md。GitHub 会按照斜杠自动创建目录层级。然后把下面的 Markdown 放入编辑器：

## 变更说明


## 复现步骤
1.
2.
3.


## 实际结果与预期结果
- 实际结果：
- 预期结果：


## 验证信息
- 测试环境：
- 测试命令：
- 验证结果：


## 风险与回滚
- 影响范围：
- 回滚方式：


## 提交前检查
- [ ] 已关联 Issue 或说明无需关联
- [ ] 已补充最小复现步骤
- [ ] 已完成测试并填写结果
- [ ] 已检查敏感信息

是 Markdown 中的 HTML 注释。它能在编辑状态提醒作者，却不会在正常渲染的 Pull Request 正文中显示。提示语应说明“要填什么”，不要堆成长篇制度；真正需要保留给审核者的信息放在标题和列表项中。

步骤三：通过新分支提交模板变更

1. 检查文件路径和正文后，单击右上角 Commit changes...。
2. 提交说明填写 Add pull request template。
3. 选择 Create a new branch for this commit and start a pull request。
4. 分支名填写 docs/add-pr-template，再单击 Propose changes。

即使有权限直接修改默认分支，也建议通过新分支和 Pull Request 提交模板。这样团队可以先检查提示项是否足够清楚，避免把带有歧义或敏感信息示例的模板直接推给所有贡献者。

步骤四：新建测试 Pull Request 验证自动填充

先完成并合并模板变更，使文件进入默认分支。随后从另一个测试分支创建 Pull Request：

1. 打开仓库的 Pull requests 标签，单击 New pull request。
2. base 选择默认分支 main，compare 选择测试分支。
3. 单击 Create pull request 进入标题和正文页面。
4. 确认正文自动出现“变更说明、复现步骤、实际结果与预期结果、验证信息、风险与回滚、提交前检查”。
5. 按实际改动填写内容，删除无关提示，再正式创建 Pull Request。

自动出现完整区块就是成功状态。如果正文为空，不要只刷新页面；优先检查模板是否已经合并到默认分支、文件名是否为 pull_request_template.md、目录是否为支持的位置。

需要多种模板时：使用 PULL_REQUEST_TEMPLATE 目录

同一个仓库同时处理缺陷修复、功能开发和文档更新时，可以把模板拆分到 .github/PULL_REQUEST_TEMPLATE/ 目录，例如：

.github/
└── PULL_REQUEST_TEMPLATE/
    ├── bug_fix.md
    ├── feature.md
    └── documentation.md

创建 Pull Request 时，可以通过 template 查询参数指定模板：

https://github.com/OWNER/REPOSITORY/compare/BASE...HEAD?template=bug_fix.md

请把 OWNER、REPOSITORY、BASE 和 HEAD 替换为实际值。模板文件名应全部使用英文、数字、连字符或下划线，避免团队成员复制链接时遇到编码差异。

可见状态与限制：模板能引导，但不能强制必填

Pull Request 模板本质上仍是可编辑的 Markdown。作者可以删除区块，也可以不勾选检查项，因此它不能真正强制必填。若团队需要硬性门禁，应把模板与分支保护、必需状态检查、CODEOWNERS 或自定义自动化检查结合使用。

常见问题

模板已经提交，为什么新建 Pull Request 仍然为空？

最常见原因是模板还没有进入默认分支。其次检查大小写和目录：单模板使用 pull_request_template.md；多模板使用 PULL_REQUEST_TEMPLATE 目录。不要把 Pull Request 模板误放进 ISSUE_TEMPLATE。

可以在模板中放日志和截图示例吗？

可以提供占位说明，但不要放真实访问令牌、Cookie、用户邮箱、生产数据库地址或未脱敏日志。建议提示作者粘贴“最小且脱敏”的证据，并把大体积日志放在受控的内部系统。

复现步骤应该写到多细？

以审核者在相同前置条件下能够独立得到问题为准。步骤应包含入口、输入、动作和可见结果；如果问题与版本或环境有关，把版本号、操作系统、运行模式等写入验证信息。

最终确认清单

• 模板文件已经合并到默认分支；
• 模板要求填写变更说明、复现步骤、实际与预期结果；
• 验证信息包含环境、命令和结果，而不是只写“测试通过”；
• 风险与回滚项能够说明影响范围和恢复办法；
• 测试 Pull Request 的正文自动带出全部区块；
• 模板中没有账号、令牌、真实客户数据或其他敏感信息。

完成这些检查后，模板就从“格式装饰”变成了评审入口：作者在发起 Pull Request 时补齐上下文，审核者拿到链接后可以先复现、再核对修改、最后验证结果，减少往返追问。