Pull Request 流程

Pull Request（PR）是 协作的正式交接点：把分支上的 commit 变成可讨论、可测试、可 merge 的变更包。本课衔接 git-essentials，聚焦 描述质量、变更粒度、Review 闭环——Git 会操作不等于 PR 写得专业。

学习目标

• 写出清晰的 PR 标题与描述（含 Test plan）
• 控制 PR 粒度：小、可审、可回滚
• 走完从 branch → push → Review → merge 的完整流程

PR 描述模板

## 做什么
一句话 + 链接 issue/课时

## 为什么
背景与取舍（若有多方案）

## 怎么测
- [ ] 单元测试：`mvn test -Dtest=...`
- [ ] 手动：步骤 1…2…

## 风险 / 回滚
影响面、feature flag、数据库迁移

Review 者 30 秒内应能判断 该不该点开 diff。AI 辅助 PR 时披露 AI-assisted 并人工验证 Test plan，见 ai-coding-essentials。

粒度原则

好 PR	差 PR
单一目的（修 bug / 加字段）	顺手重构 + 换依赖 + 改格式
<400 行有效 diff（经验值）	一次改 40 文件
可独立 revert	merge 后才发现半套功能

与 git-essentials 的 feature branch 配合：一个分支一个故事。纯重构另开 PR，便于 cq-reviews 审结构而不混行为变更。

Merge 前检查

1. CI 绿（含 testing-essentials 层级的测试）
2. 至少一位 Approve（团队可定 CODEOWNERS）
3. 冲突已解且 解冲突后重跑 CI
4. 文档/API 注解已同步（cq-docs）

Spring 项目注意 Flyway/Liquibase 脚本与 spring-boot-essentials 配置变更是否在描述中说明。

练习

• 用本节模板为「给 Track API 加分页参数」写 PR 描述（不必真开 PR）
• 读 git-pull-request（或 workflow 课），对照本地习惯差一项
• 找出历史上一個「过大 PR」，拆成 2 个更小的逻辑单元

小结

好 PR = 清晰意图 + 小粒度 + 可验证 + Review 闭环。 下一课把质量与测试金字塔连起来。