第 6 章 PR 规范

PR 是代码进入 main 的唯一入口。一个 PR 只做一个完整功能，涉及多个独立修改就拆成多个 PR。

6.1 提交前自检

检查项	要求
编译通过	本地完整编译，无报错
单元测试通过	新增 / 修改模块测试全过
示例数据通过	用仓库示例数据运行符合预期
不破坏旧功能	回归 / 基准无退化
代码风格一致	符合 Commit 与 Review 规范
无敏感信息	无密码、密钥、内部地址、私人邮箱

不得把本地分支直接推到 main 或任何受保护分支。

6.2 PR 模板字段

填全八节（完整模板在 .github/PULL_REQUEST_TEMPLATE/feature.md）：

1. 修改背景（关联 Issue / 实验 / 论文）
2. 修改内容（按文件 / 模块列出）
3. 测试环境（OS / 编译器 / 依赖版本）
4. 测试数据（来源 / 规模 / 参数）
5. 测试结果（修改前后指标）
6. 风险评估（是否影响功能 / 是否更新文档）
7. 影响范围（模块 / 配置 / 实验流程）
8. 关联 Issue（Closes # / Refs #）

完整填写示例如下（在 members/zhangsan.md 基础上新增 lisi.md，分支 feature/add-lisi）：

## 1. 背景
为复现仓库补充第二位成员"李四"的身份与分工信息。

## 2. 修改内容
- 新增 `members/lisi.md`（成员卡片，5 字段齐全）
- 更新 `members/README.md` 索引

## 3. 测试环境
Windows 11 / Git 2.43 / Python 3.11

## 4. 测试数据
name=李四、role=开发、contact=lisi@lab、joined=2026-07-20、task=周跳探测

## 5. 测试结果
运行 `python scripts/check-members.py`：
✓ zhangsan.md 字段校验通过 (5/5)
✓ lisi.md 字段校验通过 (5/5)

## 6. 风险评估
仅新增成员信息，不影响功能与实验流程，无敏感数据。

## 7. 影响范围
模块：members/；配置：无；实验流程：无。

## 8. 关联 Issue
Closes #12（添加李四成员卡片）

完整填写示例见本节末尾（上文代码块）。

6.3 PR 标题

格式与 commit 一致：<type>(<scope>): <subject>。例 feat(members): 添加周跳探测滑动窗口。反例 update、fix bug。

6.4 创建流程

本地通过自检 → git push -u origin <branch> → Web 建 PR，目标 main → 填模板 → 指定至少一名维护者审核 → 关联 Issue。

6.5 审核结果

结果	操作
通过（Approve）	维护者合并
需修改（Request Changes）	开发者在原分支修复后重提
关闭（Close）	说明理由，PR 不再推进

6.6 WIP 与大型开发

• 开发中的 PR 标题加前缀 [WIP]，审核人可暂不处理；功能完整后去掉再走正式 review。[WIP] 不合并。
• 大功能拆成多个最小完整功能 Issue，每个 Issue 对应一个完整 PR。不要把半成品大 PR 合入 main。
• PR 行数不作硬上限，但过大时先考虑拆成几个 Issue / PR。

6.7 常见错误

错误	正确做法
未填模板直接提 PR	按八节逐项填
一个 PR 含多个无关修改	拆分为多个 PR
合并后未删分支	立即删本地与远程分支
PR 未关联 Issue	用 `Closes #` / `Refs #`
审核人在 PR 里直接改代码	标注修改项，由开发者修复重提

6.8 练手：在自己的 Fork 上提一个规范 PR

在 lab-git-practice 里练一个完整的八节 PR。因为是你自己的 Fork，你既是提交者也是审核人，全程无需他人审批。

1. 本地通过自检后推分支：

python scripts/check-members.py
git push -u origin feature/add-<name>

1. Gitea 网页 Pull Requests → New Pull Request，源分支 feature/add-<name>，目标 main。（界面操作截图见 §2.8）
2. 标题写成 <type>(<scope>): <subject>，例 feat(members): 添加李四成员卡片（反例 update、fix bug）。
3. 正文套用模板 .github/PULL_REQUEST_TEMPLATE/feature.md，八节逐项填全；"测试结果"一节贴 check-members.py 的输出。完整填好的示例见第 6.2 节末尾。
4. 给自己写一条 review 意见或直接 Approve，并用 Closes #<Issue号> 关联第 7 关建的 Issue。
5. 自己点 Merge，合并方式见 docs/setup-gitea.md。

目视自检（网页关）： 在 Gitea 上对照以下清单逐项确认即可（纯中文界面，无需脚本）：

• 用八节模板（.github/PULL_REQUEST_TEMPLATE/feature.md）提 PR，"测试结果"一节贴 check-members.py 输出
• 标题为 <type>(<scope>): <subject>
• 八节字段填全；一个 PR 只做一件事；无 WIP
• 用 Closes #<Issue号> 关联第 7 关建的 Issue

---