合并与审查

合并与审查 是把一次改动交给别人看的那道口子：说明写清怎么验证、人定了什么、什么没查，评审的人才有的可审。只写「改了什么」，他只能从差异里反推意图。

合并请求是进入 main 的唯一入口。说明只写「改了什么」，评审的人只能从差异里反推意图。

如果是第一次提合并请求，整段抄合并请求模板。

本层判断标准

这份说明里的四栏（怎么验证、人定的选择、未查项、新增依赖），是不是都填了具体内容或明确的「无」？

提交前先看这四栏：怎么验证、人定的选择、未查项、新增依赖，每一栏都要有具体内容或明确的「无」。留白或写「略」，评审人会直接退回。今天补的成本是 5 分钟；不补，成本是评审人 10 分钟加一次猜错。

一次合并请求的流程

六步，每步都有一个人负责、一个命令或一个时限。跳过哪一步，后面接手的人就要补回来。

第一步（写代码的）：开分支并推送跑 git switch -c feat/notes-paging，标题带需求编号，例如 [#412] 笔记列表分页。
第二步（写代码的）：填满四栏空栏写「无」，不写「略」或「稍后补」。四栏没填完，不要点「请求评审」。
第三步（门禁）：机器先跑make check 在合并请求上自动执行。退出码非零就停在这一步，不占评审人的时间。
第四步（至少一名评审人）：批准评审等待 ≤ 1 个工作日。改动碰到高风险路径，还要由 CODEOWNERS 指派的复核人另做 30 分钟深审。
第五步（写代码的）：改完并逐条回复每条「阻塞」评论都要在 24 小时内回复；改完再推同一个分支，门禁自动重跑。
第六步（写代码的）：合并并删分支用 squash 合并，标题沿用合并请求标题；合并后删除分支，不让下一轮基于旧分支继续开发。

边界：一个人做一个项目时，「至少一名评审人」这步不适用。替代做法是把门禁调严——覆盖率 ≥ 80%、圈复杂度 ≤ 8，并在说明里写明这次没有人工评审。不要把批准栏空着不解释，那会让后面读历史的人以为漏了一步。

合并请求模板

四栏怎么填，后面那份示例照抄改数字就行。

.github/pull_request_template.md

放进 .github/ 目录后，每次新建合并请求会自动带上这份内容。

## 怎么验证的

- 命令：
- 结果：
- 手工复验：

## 人定的选择

- 决定的：
- 助手建议：
- 否掉的理由：

## 未查项

- 未查：
- 为什么不查：

## 新增依赖

- 无 / 有：
- 若新增：库名与许可、替代方案、移除方式

填写示例（四栏各一段，可照抄格式）

把下面的内容替换进上面模板对应的位置。

## 怎么验证的

- 命令：make check
- 结果：132 passed；新增行覆盖率 74%；gitleaks 与 pip-audit 均无命中
- 手工复验：用别的班级 scope_id 请求 GET /notes，返回 404，正文与「记录不存在」一致

## 人定的选择

- 决定的：分页默认 20 条；空结果文案为「还没有记录」
- 助手建议：默认 50 条，空结果复用搜索页的「没有找到相关内容」
- 否掉的理由：一屏放不下 50 条；复用搜索文案会让用户以为是自己搜索词的问题

## 未查项

- 未查：同一 note 行的并发写入行为
- 为什么不查：本学期没有压测环境；已记录到 docs/high-risk.md 的待办，下周补

## 新增依赖

- 有：httpx==0.27.0（MIT）
- 替代方案：标准库 urllib.request，不支持连接池与超时重试，已排除
- 移除方式：只在 app/clients/llm.py 里引用，换掉这一个文件即可

四栏里「人定的选择」最容易被当成形式。它真正的用处是出事后能分清边界：模型建议了什么、否掉了什么。这一栏和溯源与责任里的尾部字段是同一份信息的两个落点——一处写在合并请求说明，一处写在提交信息。

助手交出来的样子

## 怎么验证的
- 命令：make check
- 结果：全部通过
## 人定的选择
- 决定的：分页默认每页 20 条
- 助手建议：分页默认每页 20 条
- 否掉的理由：无
## 未查项
- 未查：无
## 新增依赖
- 无

认它的办法：看「人定的选择」里有没有一条与助手建议相反。四栏都填了、格式也对，可「决定的」和「助手建议」一字不差、「否掉的理由」写无——这份说明是助手写的，人一个字没动。真正过审的说明里，通常至少有一条是助手不赞成、人坚持下来的。

评审时看什么

这张表按改动类型给出要看的地方和一条判据。别对着一份只改文档的请求审满 30 分钟。

改动类型看哪里判据不看什么
文档与注释与既有文档是否矛盾没有和规约冲突的表述措辞风格
新增函数或模块输入校验、失败路径、是否有测试存在一条边界用例，且不吞掉异常命名偏好
接口行为变化字段增删、状态码、向后兼容旧调用方不改也能工作实现细节
权限与身份判定发生在哪一层、有没有绕过路径过滤条件来自会话，不来自请求体测试是否通过
金额与幂等精度、舍入、重复提交重复提交不产生第二笔扣减测试是否通过
数据删除与迁移删除范围、备份、回滚步骤执行前有 SELECT，回滚步骤可执行脚本是否跑过
新增依赖说明的「新增依赖」一栏、仓库内是否已有同类填了库名、许可、替代方案、移除方式库本身流不流行
指令与配置文件AGENTS.md、规则、钩子、工作流的逐行改动没有新增「不必检查」这类表述改动行数多少

空格和换行以代码格式的工具为准，在评审里提这类意见会被当成噪音。接口兼容性判据见接口。最后一行「指令与配置文件」是助手时代新增的，怎么审它，写法见指令与配置保护。

评论怎么写

写评论时先带前缀——阻塞、建议、提问三选一，提请求的同学才知道这条要不要改。

评论前缀与示例

直接照这三行的句式写。

阻塞：未登录时仍从请求体读取了 scope_id，必须改为从会话读取。24 小时内回复。
建议：这个函数已超过复杂度上限（当前 12，上限 10），可以拆出校验。可由作者决定是否本次改。
提问：预发环境也会跑这条迁移吗？影响我是否要准备回滚。

时限按前缀走：阻塞项的提出者在 24 小时内回复并改完；建议项可以留到下一次合并请求，但要在本次说明里记一句「留下未改」；提问由提请求的同学回复，来回超过 3 轮就当面讲——评论串拉到没人愿意读的时候，这条意见等于没提。