合并请求描述模板：字段清单与填写规范

合并请求描述模板的价值，在于让评审者不追问也能判断这次改动是否可信、是否具备合入条件。一份可用的模板应覆盖变更内容、影响与风险、验证证据、评审与合入信息四类字段，其中变更摘要、变更原因、影响范围、验证方式、关联工作项和回滚方案建议设为必填，其余字段按变更类型选填。下面给出可直接复制的空白字段表、逐字段说明、必填规则、完整填写示例与维护方法。

要点总览（TL;DR）

• 合并请求描述模板按四类字段组织：变更内容、影响与风险、验证证据、评审与合入信息，顺序对应评审者的理解路径。
• 变更摘要、变更原因、影响范围、验证方式、关联工作项、回滚方案建议设为必填，其余字段按变更类型触发填写。
• 小修复可压缩摘要与原因，常规功能需补改动清单和验证结果，高风险变更需把兼容性说明与回滚方案写到可执行步骤。
• 模板落地后按“删掉这个字段评审者是否必须追问”裁剪，每季度检查填写率，并让合入条件与评审检查项使用同一套表述。

可复制空白模板：合并请求描述字段表

把下表复制到团队的合并请求描述默认内容或文档模板中，按分组顺序填写。顺序本身有含义：先让评审者理解改了什么，再判断风险，然后核对验证证据，最后确认合入条件。

分组	字段	填写内容	填写位置与顺序
一、变更内容	变更摘要		描述开头第一段，一到三句话
	变更原因		紧随摘要，说明要解决的问题或需求背景
	改动清单		按模块或文件列出主要改动点
二、影响与风险	影响范围		改动清单之后，标明受影响的模块、接口、数据或用户场景
	兼容性说明		影响范围之后，说明接口、数据格式、配置的兼容情况
	回滚方案		兼容性说明之后，写清回滚步骤与前置条件
三、验证证据	验证方式		风险部分之后，列出执行的测试类型与覆盖场景
	验证结果		验证方式之后，给出通过情况与关键数据
	证据附件		验证结果之后，附截图、日志或测试报告位置
四、评审与合入信息	关联工作项		描述末尾，填写需求、缺陷或任务的编号与标题
	评审人		关联工作项之后，列出必须评审的角色
	合入条件		评审人之后，写明合入前必须满足的检查项
	补充说明		描述最后，记录遗留问题、后续计划或需评审者特别注意的点

如果团队习惯在纯文本环境中填写，可直接粘贴下面的描述骨架，保留分组标题作为自查提示：

【变更内容】
变更摘要：
变更原因：
改动清单：
- 
- 

【影响与风险】
影响范围：
兼容性说明：
回滚方案：

【验证证据】
验证方式：
验证结果：
证据附件：

【评审与合入信息】
关联工作项：
评审人：
合入条件：
补充说明：

字段说明：每个字段回答评审者的什么问题

字段名只是索引，真正决定填写质量的是它要回答的问题。下表按四类分组说明每个字段支撑的判断，填写时可以用“评审者看完这段能否直接下结论”作为自查标准。

字段	回答的问题	支撑的判断
变更摘要	这次改动做了什么？	改动理解：评审者据此决定重点看哪些文件
变更原因	为什么要改？不改会怎样？	改动理解：判断方案是否对准了真实问题
改动清单	具体动了哪些模块或文件？	改动理解：建立阅读顺序，避免遗漏关键改动
影响范围	改动会波及哪些模块、接口、数据或用户场景？	影响评估：决定需要哪些角色参与评审
兼容性说明	对已有接口、数据格式和配置有什么影响？	影响评估：判断是否需要灰度、迁移或通知下游
回滚方案	出问题时怎么退回去？	影响评估：确认合入后的可恢复性
验证方式	做了哪些测试？覆盖了哪些场景？	可信度判断：确认验证与影响范围匹配
验证结果	测试结果如何？有没有失败项？	可信度判断：确认改动经过实际运行
证据附件	在哪里能看到截图、日志或报告？	可信度判断：让结论可复核
关联工作项	这次改动对应哪个需求或缺陷？	合入决策：确认改动范围与需求一致，便于追溯
评审人	谁必须看？谁可以知会？	合入决策：明确评审责任与通过条件
合入条件	满足什么条件才能合入？	合入决策：把检查项前置，减少反复沟通
补充说明	还有什么需要评审者特别注意？	合入决策：记录遗留问题与后续安排

四类字段对应评审过程的不同阶段：变更类字段帮助评审者快速建立上下文，风险类字段决定评审深度和参与角色，验证类字段决定评审者能否信任作者的自测结论，关联与流程类字段则把改动放回需求与发布节奏中，支撑最终的合入决定。填写时如果某个字段写不出内容，通常说明改动本身还没想清楚，而不是字段多余。

必填与选填：按变更类型区分填写强度

所有字段都必填会让小改动填写成本过高，最终演变成敷衍填写；字段过少又会让高风险改动缺少判断依据。可行的做法是固定一组必填字段，再按变更风险调整其余字段的填写强度。

必填字段清单

• 变更摘要：没有摘要，评审者需要从代码反推意图，评审成本大幅上升。
• 变更原因：缺少原因时无法判断方案是否合理，也无法在后续回溯时解释改动。
• 影响范围：决定评审角色和测试范围，是所有变更都需要的判断输入。
• 验证方式：让评审者知道结论来自哪些测试，而不是只看“已自测”。
• 关联工作项：把改动与需求或缺陷对应起来，支撑追溯和发布说明。
• 回滚方案：任何进入主干的改动都需要可恢复路径，哪怕只是一行命令。

选填字段与触发条件

字段	触发填写的条件
改动清单	改动涉及三个以上文件或两个以上模块时填写
兼容性说明	涉及接口签名、数据格式、配置项或对外协议变化时填写
验证结果	存在自动化测试或需要说明失败项处理方式时填写
证据附件	改动涉及界面、报表或难以用文字描述的运行时行为时填写
评审人	需要跨模块或跨角色评审时明确列出
合入条件	存在发布窗口、灰度安排或依赖其他改动时填写
补充说明	有遗留问题、已知限制或后续计划时填写

按变更类型调整填写强度

• 小修复（文案、日志、单点缺陷）：必填字段保留，摘要和原因可各写一句，影响范围写“仅影响某页面某提示”，回滚方案写清还原方式即可。改动清单、证据附件可省略。
• 常规功能：必填字段完整填写，改动清单和验证结果必须写，涉及界面的补充截图。合入条件写明需要通过的检查项。
• 高风险变更（数据结构、公共接口、权限、支付等）：全部字段填写，兼容性说明和回滚方案需要写到可执行步骤，证据附件附上关键日志，评审人列出必须签字的角色，合入条件与发布窗口对齐。

填写示例：一次功能变更的完整描述

以下为演示情景，用于展示字段之间的对应关系，非真实项目案例。假设一次改动为“订单列表增加按支付状态筛选”。

【变更内容】
变更摘要：订单列表页新增按支付状态筛选，支持待支付、已支付、已退款三种状态组合查询。
变更原因：客服反馈查询特定支付状态的订单需要逐页翻找，需求单 REQ-1042 要求在本期上线该筛选能力。
改动清单：
- 订单查询接口增加 payStatus 参数，默认不过滤
- 列表页增加状态下拉筛选组件
- 补充接口参数校验与前端空状态提示

【影响与风险】
影响范围：订单列表页、订单查询接口；不影响订单详情与支付回调逻辑。
兼容性说明：payStatus 为可选参数，未传时行为与旧版本一致；旧版客户端不受影响。
回滚方案：回滚本次发布的前后端版本即可，无数据结构变更，无需数据修复。

【验证证据】
验证方式：接口层补充三种状态及组合查询的单元测试；页面层手工验证筛选、清空筛选、无结果三种场景。
验证结果：单元测试全部通过；手工验证三种场景结果符合预期，无结果时展示空状态提示。
证据附件：筛选结果与空状态截图见测试报告附件；接口测试日志见构建记录。

【评审与合入信息】
关联工作项：REQ-1042 订单列表按支付状态筛选
评审人：订单模块负责人、前端负责人
合入条件：单元测试通过、前端负责人评审通过、随本期发布窗口合入
补充说明：暂不支持按支付时间范围组合筛选，已记录为后续需求。

对照模板可以看到：摘要和原因回答了“改了什么、为什么改”，影响范围与兼容性说明限定了评审边界，回滚方案给出了可执行动作，验证方式与结果对应影响范围中的两个层面，关联工作项把改动接回需求。评审者读完这份描述，可以直接判断需要重点看接口参数校验和前端空状态处理，而不必先问作者。

当团队把合并请求与需求、任务放在同一协作平台管理时，关联字段可以进一步落到具体工作项上。例如在 ONES 中，需求与文档可以互相对应，评审说明、验证记录可以沉淀在关联文档里，评审者从工作项即可看到改动背景与验证证据；ONES Wiki 支持富文本、Markdown 与代码块，成员可在线添加注释和评论，适合承载模板与评审记录，页面版本可查看与回滚，便于回溯描述的历史修改。具体关联方式和权限以实际开通的版本为准。

调整与维护：让模板随团队实践演进

模板落地后最常见的两个问题是字段越加越多、填写越来越敷衍。维护的重点是让每个字段都有明确的判断用途，并定期清理不再被使用的字段。

按团队规模与变更风险裁剪

• 人数较少、改动集中在单一模块的团队，可先保留六个必填字段，把改动清单与证据附件合并为一段自由描述。
• 多人协作、跨模块改动频繁的团队，保留完整分组，并对高风险变更增加评审人签字要求。
• 裁剪时以“删掉这个字段，评审者是否必须追问”为判断标准，需要追问的字段保留。

新增字段的准入判断

新增字段前先回答三个问题：它支撑的是哪一类判断（改动理解、影响评估、可信度或合入决策）；过去一个月是否出现过因缺少该信息而返工的评审；能否用现有字段表达。三个问题都有明确答案时再新增，并同步更新模板、字段说明和示例三处，保持名称一致。

定期回顾与废弃字段处理

• 每季度抽取若干合并请求，检查各字段的实际填写率与有效信息比例。
• 连续两个周期填写率低且未被评审使用的字段，标记为选填或移出模板，并在团队文档中记录移除原因。
• 回顾时同步核对示例是否仍与模板一致，避免示例停留在旧字段上。

与评审检查项、合入条件的衔接

模板中的“合入条件”应与团队的评审检查项使用同一套表述，例如“单元测试通过”“接口兼容性确认”“回滚步骤已验证”。这样描述里的条件可以直接对应到合入前的核对动作，减少描述与检查两张皮的情况。检查项调整时，同步修改模板中的合入条件字段，并在下一次回顾中确认填写示例已更新。

常见问题

合并请求描述写得很短，评审者仍然能看懂，是否还需要完整模板？

描述长短取决于改动本身，模板的作用是提供判断清单，而非要求每项都写满。改动只涉及一处文案或日志时，摘要和原因各写一句、影响范围写清受影响的页面、回滚方案写清还原方式，就已经覆盖了评审者的判断需要。字段可以压缩，但“改了什么、为什么改、影响哪里、怎么退回去”这几个问题需要有答案，否则评审者只能从代码反推意图。

模板里的字段和评审检查项、合入条件是什么关系？

描述模板负责把改动背景和验证证据交给评审者，评审检查项负责在合入前逐条核对，两者应使用同一套表述。例如模板中的合入条件写“接口兼容性确认”，检查项里也应有对应的核对条目，这样描述里的条件可以直接对应到合入前的动作。检查项调整时同步修改模板中的合入条件字段，避免描述与检查各写一套。

团队已经在用固定的合并请求描述默认内容，还需要单独维护模板文档吗？

默认内容解决“每次新建都带上字段”，模板文档解决“字段为什么存在、怎么填算合格”。两者可以配合：默认内容放空白字段骨架，模板文档放字段说明、必填规则和填写示例，供新成员查阅和团队回顾时对照。如果只有默认内容，字段容易在多次修改中悄悄增减，缺少判断依据；如果只有文档，填写时又要反复复制。把骨架和说明分开维护，更新时同步修改两处即可。

高风险变更的评审人字段应该写到什么程度？

高风险变更建议在评审人字段中列出必须签字的角色，而不只是写“相关同学”。例如涉及数据结构变更时写明后端负责人与数据负责人，涉及支付逻辑时写明支付模块负责人。角色明确后，合入条件可以写成“以上角色评审通过”，评审责任与通过标准就落在同一处。角色名称按团队实际分工填写，不必套用固定职级。

模板字段较多时，能否放到团队知识库里统一维护？

可以。把空白字段表、字段说明和填写示例放在团队知识库的同一页面，合并请求描述默认内容只保留纯文本骨架并指向该页面，能减少多处维护不一致的问题。以 ONES Wiki 为例，页面支持富文本、Markdown 与代码块，成员可在线添加注释和评论，页面版本可查看与回滚，适合承载模板与评审记录；需求与文档可以互相对应，评审说明和验证记录可沉淀在关联文档中。具体关联方式与权限以实际开通的版本为准。