需要把代码改动打包成可评审的 PR 时：规范标题与描述…

当你在功能分支上完成（或接近完成）改动，需要创建一个标题规范、描述结构化、已自审且带评审人的 pull request 时使用。

适用场景

解决思路

1. 创建 PR 前先运行 `git fetch origin`，让分支与 base 保持同步，再按项目惯例执行 `git rebase origin/main`（或 merge）。
2. 用 `git log origin/main..HEAD --oneline` 和 `git diff origin/main --stat` 检查本次 PR 将包含哪些提交和改动。
3. 若项目偏好整洁历史，就 squash 掉 fixup 提交；若偏好细粒度历史，则保留各个逻辑提交。
4. 标题使用格式 `<type>: <short description>`。
5. 按改动性质选择 type：`feat` 新功能；`fix` 修 bug；`refactor` 既不修 bug 也不加功能的代码改动；`docs` 仅文档；`test` 新增或修复测试；`chore` 构建、CI、依赖或工具；`perf` 性能优化。
6. 标题参考示例：`feat: add dark mode toggle to settings page`、`fix: prevent duplicate form submissions on checkout`、`refactor: extract auth middleware into shared module`。
7. 描述采用固定结构：`## Summary` 用 1-3 句话说明这个 PR 做了什么、为什么，并用 `Closes #123` 关联 issue。
8. `## Changes` 用要点列表列出具体改动（例如新增 `ThemeToggle` 组件、让 `Layout` 从 context 读取主题、把主题持久化到 localStorage）。
9. `## Test Plan` 用 checklist 列出人工验证步骤（例如在 light/dark/system 间切换、刷新页面后主题保持、检查加载时无样式闪烁）。
10. 请求评审前通读自己 diff 的每一行。
11. 移除调试代码：`console.log`、`TODO`、被注释掉的代码。
12. 验证测试通过：`npm test`。
13. 验证类型：`npx tsc --noEmit`。
14. 验证 lint：`npm run lint`。
15. 检查不应提交的文件：`.env`、lockfile 冲突。
16. 推送分支：`git push -u origin HEAD`。
17. 用 `gh pr create --title "<title>" --body "$(cat <<'EOF' ... EOF)"` 创建 PR，body 中写入 Summary、Changes、Test Plan 三段。
18. 标记合适的 reviewer（code owners、领域专家）。
19. 若 PR 较大（>400 行），加一条评论说明按什么顺序阅读文件最佳。
20. 若该 PR 依赖另一个 PR，在描述中注明。
21. 给 PR 打上合适的 label（feature、bug、breaking change 等）。
22. 保持 PR 尽量小，改动目标 <300 行。
23. PR 过大时拆成 stacked PRs。
24. UI 改动附上截图或录屏，能显著加快评审。
25. 工作尚未完成但想先拿早期反馈时，用 draft PR。
26. `gh pr create` 仅适用于 GitHub；若项目用其他平台（如 GitLab），改用对应 CLI 或 Web 界面创建 PR。
27. 若项目对提交历史/合并方式有强制约定（如必须 squash），以项目约定为准，不要照搬本文默认做法。
28. 只是想把代码推上去备份或同步、还没打算让人评审时，不必走完整的 PR 流程。

适用边界 · 注意事项

• 项目不使用 GitHub 或未安装 `gh` CLI 时，第 5 步的命令需替换为对应平台的工具或 Web 界面操作。
• 改动尚未成形、只想拿早期反馈时，不必按完整流程写描述和指定 reviewer，直接用 draft PR 更合适。