PR模板如何引导高质量提交

本文目录导读：

1. 建立清晰的PR模板（强制要求）
2. 配合自动化检查（CI/CD）
3. 贡献指南中的“好PR准则”
4. 设定“链式阻塞”规则（可选但高效）
5. 培养“Review文化”而非“KPI文化”
6. 低摩擦工具（减少贡献者的心智负担）
7. 总结：高质量PR的“铁三角”

要引导高质量的PR（Pull Request），关键在于将“抽象的标准”转化为“具体的流程和工具”，让贡献者从一开始就清楚什么是“好”的PR，以下是分层次的引导方法：

建立清晰的PR模板（强制要求）

模板是最高效的“第一道过滤器”，在仓库根目录创建 .github/PULL_REQUEST_TEMPLATE.md（支持多个模板）。

高质量模板应包含的字段：

## 描述
<!-- 清晰说明此PR解决的问题，包括背景、动机和影响。 -->
- **关联Issue**: #[Issue编号]
- **类型**: (Bug修复 / 新功能 / 性能优化 / 文档 / 重构 / 其他)
<!-- 列出主要变更点，不要只写“修复bug”，要具体到文件名和函数。 -->
1. `src/login.ts`：修复了OAuth过期后的重定向逻辑
2. `webhook/handler.go`：新增了签名验证中间件
## 测试
<!-- 描述如何测试这些更改，包括单元测试、集成测试或手动测试步骤。 -->
- [ ] 单元测试覆盖新逻辑 (覆盖率 >= 80%)
- [ ] 已通过现有测试套件
- [ ] 手动测试步骤：打开设置页 -> 点击“保存” -> 检查API响应
## 影响范围
<!-- 是否破坏向后兼容？是否修改了数据库Schema？是否需要更新文档？ -->
- [ ] 破坏性变更 (需要MAJOR版本更新)
- [ ] 需要同步更新文档
## 前置PR依赖（可选）
<!-- 此PR是否依赖其他未合并的PR？ -->
- #123
## 截图/视频（如果是UI变更）
<!-- 贴出变化前后的对比，或操作演示的录屏链接。 -->

配合自动化检查（CI/CD）

模板只是起点,自动化工具能强制执行标准：

• Lint/格式检查：如 ESLint、Prettier、Black（Python）、gofmt，PR不通过格式检查直接标记为“需修改”。
• 测试覆盖率阈值：使用 Codecov 或 Coveralls，设定“新代码覆盖率必须 >= 80%”，否则CI失败。
• 静态类型检查：TypeScript 的 strict 模式、mypy（Python）、Flow。
• Commit 规范检查：使用 commitlint 结合 husky 强制 commit message 格式（如 feat: ... 或 fix: ...）。
• 安全检查：如 truffleHog 检测敏感信息泄露，snyk 检测依赖漏洞。

贡献指南中的“好PR准则”

在 CONTRIBUTING.md 中明确写出期望（而非命令），可附上正反例子：

❌ 低质量PR特征：为空或过于模糊（如“更新代码”、“修复bug”）

• 描述为空或只有一句“修复了问题”
• 一个PR包含3个以上不相关的功能（没有拆分）
• 提交了压缩后的二进制文件或 node_modules
• 没有关联任何 Issue，且没有说明为什么要做

✅ 高质量PR特征：是动宾结构，不超过50字：fix(auth): resolve session expiration on token refresh

• 描述包含“做了什么”和“为什么做”，且提到了影响范围
• 有且仅有一个功能点或bug修复（遵循原子化提交）
• 包含了测试用例,且通过了
• 代码中包含了必要的注释和类型声明（而非一堆魔法数字）
• 没有无用的文件格式变更（如编辑器自动添加的空格）

设定“链式阻塞”规则（可选但高效）

• Issues 必须先有讨论：PR应关联已标记为“需要修复”或“已批准设计”的 Issue，如果没有关联，管理员可关闭PR并要求先开Issue。
• 高风险变更要求多人Review：配置 CODEOWNERS 文件，对核心模块（如数据库、支付）设定必须由特定团队资深成员 approve。

  /database/migrations/ @core-team-leads
  /payment/ @security-team
  *.config.ts @infrastructure

• 合并方式：仅允许 Squash merge 或 Rebase merge，禁止直接 Merge（Commit 历史干净）。

培养“Review文化”而非“KPI文化”

• Review checklist：在PR模板中附带一个供Reviewer使用的 checklist，不满足则可直接请求修改（Request Changes）。
  • 错误处理是否全面（try-catch覆盖到合理的粒度）？
  • 是否有魔法字符串/数字需要提取为常量？
  • API响应码是否使用了HTTP标准（如201表示创建成功）？
• 正面激励：在团队周会或文档中，公开表扬那些“模板填写完整、自测充分、收到极少修改请求”的PR，树立榜样。

低摩擦工具（减少贡献者的心智负担）

• Commitizen：提供交互式 commit message 输入（git cz 代替 git commit）。
• PR 自动化填写：使用 GitHub Actions（Danger.js）在PR创建后自动检查模板字段是否填写完整，不完整则留言提醒。
• 预览环境（Preview deployment）：为每个PR自动部署一个临时环境（如 Vercel/Netlify/Cloudflare Workers），让 Reviewer 可以直接点击访问并验证UI/API变化。

高质量PR的“铁三角”

永远不要把 PR 模板写得像“考试问卷”——它应该是一个“帮助贡献者思考”的向导，当贡献者按照模板填写完所有内容时，他们通常已经自动完成了一半的 self-review。