合并请求描述模板的字段取舍标准只有一条：评审者能否据此判断这次变更该不该合入。围绕这个标准，一份精简模板通常包含变更目的与关联需求、改动范围与影响面、验证方式与结果、风险与回滚方案、评审关注点、合入前置条件六类字段，其余背景信息用链接或附件补充。下面先给出可直接复制的空白模板，再逐项说明字段作用、必填划分、填写示例与维护方法。
要点总览（TL;DR）
- 合并请求描述模板的字段取舍标准是：评审者能否据此判断这次变更该不该合入；围绕这个标准，模板通常包含六类字段。
- 六类核心字段是变更目的与关联需求、改动范围与影响面、验证方式与结果、风险与回滚方案、评审关注点、合入前置条件。
- 前四类建议作为必填项；评审关注点与合入前置条件可按团队约定选填，紧急合入时保留验证结果与回滚方案，其余事后补齐。
- 模板控制在半屏以内，长内容用链接或附件补充；可保存为仓库模板文件，新建合并请求时自动带出结构。
- 模板维护以评审中反复被追问的信息为增补依据，连续多个周期无人填写的字段考虑删除或改为选填。
可复制空白模板
以下模板可直接粘贴到代码托管平台的合并请求描述框中。字段顺序按评审者的阅读与判断路径排列：先知道为什么改，再看改了什么、验证过什么，最后确认风险与合入条件。方括号内为占位提示，填写后删除。
## 变更目的与关联需求 [一句话说明本次变更解决什么问题；关联需求/缺陷/任务编号，如 PROJ-123] ## 改动范围与影响面 - 主要改动：[模块/文件/接口，简述改了什么] - 影响面：[受影响的调用方、数据、配置、上下游服务] - 不包含：[本次明确不处理的相关内容，避免评审范围误解] ## 验证方式与结果 - 验证方式：[单元测试/集成测试/手工验证/灰度观察等] - 验证结果：[通过项与关键输出；未覆盖项及原因] - 补充材料：[测试报告、截图、日志链接] ## 风险与回滚方案 - 主要风险：[可能出问题的环节及触发条件] - 回滚方式：[回滚步骤、开关、数据恢复方式] - 回滚影响：[回滚期间的用户影响与耗时估计] ## 评审关注点 [希望评审者重点看的部分，如某段并发逻辑、某个兼容性处理；无特别关注点可写“无”] ## 合入前置条件 - [ ] 关联需求已确认 - [ ] 必要评审已通过 - [ ] 验证结果已附 - [ ] 发布/回滚方案已对齐
模板控制在半屏以内，长内容一律放链接。若团队使用仓库内的合并请求模板文件，可将上述内容保存为模板文件，新建合并请求时自动带出。
字段说明：每个字段回答评审者的什么问题
每个字段存在的理由，是替评审者回答一个具体判断问题。字段增删时先问：删掉它，评审者是否还能做出合入判断。下表给出字段与判断问题的对应关系。
| 字段 | 回答的评审问题 | 填写要点 |
|---|---|---|
| 变更目的与关联需求 | 这次改动为什么存在，是否对应已确认的需求或缺陷 | 一句话写清问题与目标，附需求/缺陷编号，便于追溯背景与验收口径 |
| 改动范围与影响面 | 改了哪些地方，会不会波及我负责或熟悉的部分 | 按模块列改动点，明确受影响的接口、数据与上下游；写清本次不包含的内容 |
| 验证方式与结果 | 作者用什么方式证明改动有效，结论是否可信 | 写验证手段与关键结果，未覆盖的部分说明原因，报告与日志放链接 |
| 风险与回滚方案 | 出问题时影响多大，能否快速恢复 | 指出高风险环节与触发条件，给出可执行的回滚步骤与耗时估计 |
| 评审关注点 | 作者希望我重点看哪里 | 指向具体逻辑或兼容性处理，帮助评审者分配注意力；没有则写“无” |
| 合入前置条件 | 还差什么才能合入 | 用可勾选清单列出待办，如评审通过、验证附齐、发布窗口确认 |
变更目的与关联需求决定了评审的基准：没有需求背景，评审者只能就代码论代码，难以判断改动是否完整。改动范围与影响面帮助评审者快速定位自己需要看的部分，也避免“以为没改”的遗漏。验证方式与结果是评审者判断改动可信度的主要依据，只写“已自测”信息量不足，写清测了什么、结果如何才有用。风险与回滚方案让合入决策带上代价评估，尤其对涉及数据、配置和对外接口的变更。评审关注点与合入前置条件则把评审从被动通读变成有重点的检查，并明确合入的完成标志。
必填与选填：按变更类型区分
六个字段中，变更目的与关联需求、改动范围与影响面、验证方式与结果、风险与回滚方案建议作为必填项，理由是它们直接支撑“该不该合入”的判断，缺任何一项评审者都需要额外追问。评审关注点与合入前置条件可作为选填或按团队约定处理：前者在改动简单时可写“无”，后者在流程已由平台检查项覆盖时可省略。
| 变更类型 | 必填字段 | 可简化或选填 |
|---|---|---|
| 缺陷修复 | 变更目的与关联需求（含缺陷编号与复现条件）、验证方式与结果、风险与回滚方案 | 改动范围可简写；评审关注点指向根因修复处 |
| 新功能 | 变更目的与关联需求、改动范围与影响面、验证方式与结果、合入前置条件 | 风险与回滚方案在功能默认关闭或可开关时从简 |
| 配置调整 | 改动范围与影响面、风险与回滚方案、验证方式与结果 | 变更目的可一句话带过；评审关注点写明配置生效范围 |
| 紧急合入 | 验证方式与结果、风险与回滚方案 | 其余字段可先写要点，事后补齐并在描述中注明补填时间 |
紧急合入是唯一建议放宽字段完整度的场景，但验证结果与回滚方案两项应保留，因为这两项直接决定出问题时能否止损。放宽不等于省略，可在描述中标注“紧急合入，其余字段于合入后补充”，并在事后回填，避免模板在高压场景下被整体放弃。
填写示例：一份完整的合并请求描述
以下示例为演示情景，展示各字段的具体写法，字段名称与顺序和空白模板保持一致。
## 变更目的与关联需求 修复订单列表在分页参数为空时返回全量数据的问题，关联缺陷 PROJ-482。 ## 改动范围与影响面 - 主要改动：订单查询接口增加分页参数校验，默认每页 20 条；调整查询构造逻辑 - 影响面：订单列表页、导出功能共用该接口；不影响订单详情与支付流程 - 不包含：历史数据修复，另行处理 ## 验证方式与结果 - 验证方式：补充 3 个单元测试覆盖空参数、越界页码、正常分页；测试环境手工验证列表页与导出 - 验证结果：单元测试全部通过；手工验证列表页默认返回 20 条，导出结果与筛选条件一致 - 补充材料：测试报告链接、接口返回示例 ## 风险与回滚方案 - 主要风险：导出功能依赖同一接口，分页默认值可能影响大批量导出条数 - 回滚方式：回滚本次提交并重启服务，约 5 分钟；无数据结构变更，无需数据恢复 - 回滚影响：回滚期间订单列表短暂不可用 ## 评审关注点 请重点看查询构造中分页参数与导出参数的兼容处理。 ## 合入前置条件 - [x] 关联缺陷已确认 - [x] 单元测试与手工验证完成 - [ ] 导出功能负责人确认条数变化可接受 - [ ] 发布窗口确认
示例中验证结果写到了具体条数与覆盖场景，回滚方案写到了操作方式、耗时与数据影响，评审者据此可以直接判断合入条件是否满足。合入前置条件保留未勾选项，明确当前还差导出负责人的确认，避免在条件未满足时被误合入。
调整与维护方法
模板的价值在于稳定支撑评审判断，字段随实践演进需要定期校准。建议以评审中反复被追问的信息作为增补依据：同一类问题连续多个周期在评审评论中出现，就考虑把它固化为字段；某个字段连续多个周期无人填写、也无人据此提问，则考虑删除或改为选填。模板评审可与团队回顾节奏对齐，例如每季度检查一次字段使用情况。
落地方式可以组合使用：在代码仓库中放置合并请求模板文件，让新建合并请求自动带出结构；把关键字段设为评审检查项，评审时逐项确认；在团队评审约定中写明必填范围与紧急合入的简化规则。三种方式配合，减少对个人记忆的依赖。若团队使用 ONES Wiki 沉淀评审规范，可借助其页面模板库一键创建制式化文档，把模板说明、字段口径与示例放在同一页面，并通过页面组关联项目，让需求与文档互相对应；文档记录页面版本并支持查看与回滚，模板修订过程可追溯。合并请求本身仍在代码托管平台发起，模板内容与评审规范通过文档保持同步即可。
维护中最需要防的是形式化：字段越加越多、填写变成走过场。控制手段包括保持模板半屏以内、长内容只放链接、定期清理无人使用的字段，以及在评审中真正依据字段提问——评审者不再追问模板已覆盖的信息，模板才算落地。
常见问题
合并请求描述模板字段太多，评审者反而不看，怎么精简？
精简的判断依据是字段是否直接支撑合入决策。可以逐项自问：删掉这个字段，评审者还能不能判断该不该合入。如果删掉后评审者仍能做出判断，就把它移到链接或附件里。
常见的精简做法包括：把背景说明、设计文档、测试报告放到链接中，描述里只保留结论；把合入前置条件交给平台的检查项自动展示；把评审关注点合并进改动范围，指向具体文件或逻辑。模板控制在半屏以内，评审者更可能逐项读完。
紧急合入时字段写不全，事后怎么补才不流于形式？
紧急合入时建议保留验证方式与结果、风险与回滚方案两项，它们直接决定出问题时能否止损。其余字段可以先写要点，并在描述中注明“紧急合入，其余字段于合入后补充”。
事后补齐需要有承接动作：可以在团队评审约定中指定补填时限，例如合入后一个工作日内；也可以在下次迭代回顾时抽查紧急合入的合并请求描述，确认补填完成。补填内容与合入记录放在一起，后续追溯时能对应上。
缺陷修复和新功能的合并请求描述，侧重点有什么不同？
缺陷修复的描述重点在复现条件与根因：变更目的里写清缺陷编号和触发场景，验证结果里说明修复前后行为对比，评审关注点指向根因修改处。改动范围通常较小，可以简写。
新功能的描述重点在目的与影响面：写清需求背景、新增或改动的接口与数据、对上下游的影响，合入前置条件列明评审与发布窗口。若功能默认关闭或带开关，风险与回滚方案可以从简，写明开关关闭即可。
模板放在代码仓库里自动带出，还是放在文档平台维护，哪种更合适？
两种方式解决不同问题，可以组合使用。放在代码仓库的合并请求模板文件中，新建合并请求时自动带出结构，填写入口离代码最近，适合作为日常填写的起点。
放在文档平台适合沉淀模板说明、字段口径与填写示例，方便团队查阅和修订。例如 ONES Wiki 提供页面模板库，可一键创建制式化文档，页面组可关联项目，文档记录页面版本并支持查看与回滚，模板修订过程可追溯。合并请求本身仍在代码托管平台发起，两边保持同步即可。
怎么判断某个字段该保留还是删除？
用两个信号判断。增补信号：同一类信息连续多个周期在评审评论中被追问，说明它值得固化为字段。删除信号：某个字段连续多个周期无人填写，也无人据此提问，说明它没有承担判断作用，可以删除或改为选填。
检查节奏可与团队回顾对齐，例如每季度看一次字段使用情况。调整后同步更新模板文件、字段说明与填写示例，保持三处字段名称与顺序一致，避免读者复制后对不上。
