第 2 章 质量控制
合入 main 的每一行代码须经至少一名维护者审查并签字。
2.1 审核人资格
| 角色 | 可否审核 | 条件 |
|---|---|---|
| 维护者（Maintainer） | 是 | 熟悉被审模块 |
| 管理员（Administrator） | 仅限紧急情况 | 须具备模块知识 |
| 开发者（Developer） | 否 | 无签字权 |
| 报告人（Reporter） | 否 | 无签字权 |
开发者可参与讨论、互审提意见，但最终签字权仅归维护者。
2.2 六维审查（逐项检查，缺一即不完整）
- 功能正确性：实现符合预期；边界与错误处理完备。
- 算法正确性：逻辑正确；数值精度可靠；无死循环、无无限递归。
- 命名规范：命名符合约定；注释与行为一致。
- 可复现性：参数有说明；随机种子已固定或已说明；使用相对路径；包含或引用实验记录。
- 文档完整性：具备关键注释；README、文档、CHANGELOG 已同步更新。
- 代码保密合规：无密钥、无内部 IP；未误提交数据；无外部地址。
2.3 合入策略
按 PR 性质选择合并方式，兼顾 main 线性与关键历史的保留：
| PR 性质 | 合并方式 | 理由 |
|---|---|---|
| 日常 `feature/*`、`fix/*`、`docs/*` | **Squash merge** | 把分支上的零散提交压成一条干净记录，`main` 保持线性易读 |
| 论文 / 里程碑相关、含多个有意义原子提交的 PR | **Merge commit** | 保留每个原子提交与其 commit body 四段，服务论文可复现与 Tag 绑定 |
- Squash 时，维护者需把各提交的 body 四段（背景 / 修改 / 验证 / 影响）汇总进最终的 squash 合并信息，不要让复杂提交的说明随压缩丢失。
- 合并信息标题沿用 PR 标题（
<type>(<scope>): <subject>）。 - 仅维护者可 merge；合并后勾选"删除源分支"。
- 普通 feature PR 先经一名成员互审，再由轮值维护者终审合入。
Gitea 可在「仓库 -> Settings -> Pull Requests」限制可用的合并方式，也可在每次点击 Merge 时下拉选择。
2.4 审核结果
| 结果 | 操作 |
|---|---|
| 通过（Approve） | 合并 |
| 需修改（Request Changes） | 逐行标注，开发者修复后重新提交，未修复不予合并 |
| 关闭（Close） | 附说明，PR 不再推进 |
评论应具体、可操作，避免"看起来没问题"式结论。
2.5 分支清理
- 合并后删除已合入的远程分支（Merge 时勾选或手动）。
- 本地分支由开发者
git branch -d删除；远程分支由维护者删除。 - 实验分支不合并，按第 4 章归档。
2.6 常见错误
| 错误 | 正确做法 |
|---|---|
| "看起来没问题"即通过 | 六维逐项审查，给出具体意见 |
| 开发者在 main 上修改 | 回到原分支补充 commit 后重新推送 |
| 合并后不删除分支 | 立即删除，避免分支堆积 |
| 审核人直接修改 PR 代码 | 标注修改项，由开发者修复后重新提交 |
2.7 在 Gitea 上接受并合并 PR（操作实务）
本小节操作前提是：main 已按 §1.2 设置合并白名单（Merge Whitelist）与必需批准（Required approvals），故只有维护者（白名单内用户/团队）能在 Gitea 网页端看到并点击 Merge 按钮。以下内容把 §2.2 的六维审查、§2.3 的合入策略、§2.4 的审核结果、§2.5 的分支清理，落地为"在 Gitea 网页端怎么把 PR 真的接受并合进去"的具体点击步骤；凡涉及原则，用"见 §2.x"呼应，不展开。
2.7.1 打开 PR 列表并进入目标 PR
进入原仓库后，通过 Pull Requests 标签页查看全部 PR；维护者也会在通知中收到新的 PR 提醒。
仓库 -> Pull Requests（标签页）
提示：如发现某个 PR 不打算合并，可在 PR 页面使用 Close Pull Request 按钮直接关闭（不合并即关闭）。作者若以
WIP:或[WIP]前缀标记，可防止被误合，待就绪后再去掉前缀。
2.7.2 熟悉 PR 页面的四个标签
进入任一 PR 后，页面顶部有四个标签：
- Conversation：总评、时间线与合并按钮所在处（见 §2.7.5）。
- Files changed：变更文件与 diff，可逐行查看差异、添加行内评论（见 §2.7.3）。
- Commits：本 PR 包含的提交历史。
- Checks：仅当仓库配置了 CI（如 Gitea Actions、Drone 等）时才出现，显示状态检查结果，呼应 §1.2 的状态检查。
2.7.3 在 Files changed 中做逐行审查（六维审查的落地）
六维审查的具体标准见 §2.2。这里只讲"怎么在网页端把意见落到行上"。
PR 页面 -> Files changed（标签）-> 点某行左侧 '+' 号添加行内评论- 点某一行左侧的 '+' 号，即可对该行添加行内评论；可拖选多行进行批量评论。
- 输入评论后，点 Add single comment 单次提交，或点 Start review 开始整轮审查。
- 作者修复后，点 Resolve conversation 可折叠旧评论。
2.7.4 提交 Review 动作（Approve / Request changes / Comment）
审查动作位于 PR 页面右上角绿色按钮（有出处称 "Review changes"，亦称 "Review"；你方 Gitea 1.27 实例的确切字样，请以本小节截图复核）。点击后弹出对话框写总评，再选择其一：
- Approve：计入合并所需批准数，点亮合并条件。
- Request changes：若 §1.2 开启了"在拒绝的审查上阻止合并（Block merge on rejected reviews）"，则阻止合并。
- Comment：仅留言，不计入批准也不阻止合并。
未提交的整轮审查为 Pending，须点 Review 提交后才对所有人生效。三种结果的含义与后续处理见 §2.4。
提示：审核动作的确切按钮字样与弹框布局，请以本小节已嵌入的截图，对照你方 Gitea 1.27 实例界面复核后定稿。
2.7.5 在 Conversation 底部合并 PR
审查完成（已获必需批准，见 §2.3、§2.4）后，回到 Conversation 标签底部执行合并。
PR 页面 -> Conversation（标签）-> 底部绿色 Merge Pull Request 按钮 -> 弹出合并框合并框中的合并方式下拉项（Gitea 支持三种，1.27 网页端确切字样/顺序请以本小节截图复核，概念已确认）：
- Create a merge commit：保留 feature 分支全部提交并新增一个合并提交 ← 对应 §2.3 论文/里程碑用 Merge commit。
- Squash and merge：将本 PR 全部提交压成 1 个提交 ← 对应 §2.3 日常 feature/fix/docs 用 Squash（须按 §2.3 汇总 body 四段）。
- Rebase and merge：线性重放，无合并提交，但改写提交哈希、丢弃原作者签名 ← 一般不选。
合并框中的 Delete branch 勾选项用于合并后删除源分支，呼应 §2.5。（确切措辞与是否默认勾选，请以截图复核。）
提示：合入策略的选择理由与 Squash 的 body 汇总要求见 §2.3，分支清理的后续处理见 §2.5。合并方式下拉的默认选项与勾选状态，请以截图复核后定稿。
2.7.6 为什么只有维护者能合并（分支保护关系）
§1.2 的分支保护规则解释了"为什么必须先批准、为什么只有维护者能点 Merge"：
- 合并白名单（Merge Whitelist）：只有白名单内的用户/团队能在 Gitea 看到并点击 Merge。
- 必需批准（Required approvals） ＋ 在拒绝的审查上阻止合并：必须先获得规定数量的批准。
- 状态检查（Status checks）：对应 PR 页面的 Checks 标签（见 §2.7.2）。
- 在 Gitea 1.27 中，可在分支保护规则中勾选"管理员也须遵守分支保护规则"，以禁用管理员的 Force merge 绕过。
注：本小节的分支保护设置截图尚未提供，待补
media/管理员/对应图片后插入。
2.7.7 常见误操作（补充 §2.6）
以下操作风险基于 Gitea 行为与 §2.6 推导，请合并前留意：
- 误选 Rebase and merge：会改写历史、丢失提交者签名。日常优先 Squash（见 §2.3）。
- 合并框未勾 Delete branch：遗留垃圾分支，需按 §2.5 兜底清理。
- 对
experiment/*误点合并：分支保护按模式匹配；若experiment/*不在保护规则内，则不受白名单/批准约束，合并前必须人工核对目标分支名。 - 在 PR 里直接改代码：Gitea 网页端 PR 一般不提供"在 PR 中编辑源文件"入口，reviewer 应在 Files changed 评论（见 §2.7.3），由作者本地改后推送。
- 未等批准/Checks 即合并：受 §1.2 约束时按钮本应禁用；若管理员用 Force merge 绕过，须注意 1.27 可在规则中勾选"管理员也须遵守分支保护规则"禁用该按钮（见 §2.7.6）。
合并前检查清单
| 步骤 | 操作要点 | 呼应章节 |
|---|---|---|
| 1 | 打开 PR（Pull Requests 标签，进入目标 PR） | §2.7.1 |
| 2 | 对照六维审查在 Files changed 落评论 | §2.2、§2.7.3 |
| 3 | 提交 Approve（或 Request changes） | §2.4、§2.7.4 |
| 4 | 选 Squash and merge，并勾 Delete branch | §2.3、§2.5、§2.7.5 |
| 5 | 点 Merge Pull Request 完成合并 | §2.7.5 |
| 6 | 确认 main 已更新、源分支已删除 | §2.5 |
提示：上述网页端按钮的确切字样、下拉顺序与默认勾选状态，凡标注"以截图复核"者，请对照本小节已嵌入的
media/管理员/截图，以你方 Gitea 1.27 实例界面最终确认。