一份能支撑评审和合入判断的合并请求描述，要让评审者在不追问的情况下回答四个问题：这次改了什么、为什么改、怎么验证、合入后有什么风险。可复制的模板按“变更摘要—背景与关联—改动范围—验证证据—风险与回滚—合入条件”六段组织，其中变更摘要、关联工作项、改动范围、验证方式与结果、风险与回滚为必填，截图、性能数据、评审关注点等按改动类型选填。下面先给空白模板，再逐字段说明、划分必填强度、给出完整示例，最后讲模板如何落地到团队流程。
要点总览（TL;DR）
- 合并请求描述要让评审者不追问就能回答四个问题：改了什么、为什么改、怎么验证、出问题怎么办，模板按“变更摘要—背景与关联—改动范围—验证证据—风险与回滚—合入条件”六段组织。
- 变更摘要、关联工作项、改动范围、验证方式与结果、风险与回滚为通用必填项；截图、性能数据、评审关注点、依赖变更说明按改动类型选填。
- 缺陷修复、新功能、重构、配置与依赖变更各有升级为必填的字段；紧急修复可先写清改了什么和如何回滚，合入后补记其余字段。
- 模板以纯 Markdown 文本交付，可保存为仓库合并请求模板文件或平台默认描述，并随评审追问与合入后问题定期修订。
可复制空白模板：合并请求描述六段式
以下模板为纯 Markdown 文本，可直接粘贴到任意代码托管平台的合并请求描述框中，按占位提示逐项替换即可。方括号内为填写提示，提交前应全部替换或删除。
## 一、变更摘要 [一句话说明本次改动做了什么，例如：修复订单导出在空数据时抛异常的问题] ## 二、背景与关联 - 关联工作项：[需求/缺陷/任务编号与标题] - 改动原因：[为什么要做这次改动，触发场景或业务背景] - 关联文档：[设计文档、接口文档、讨论记录链接，无则写“无”] ## 三、改动范围 - 涉及模块：[模块/服务/目录] - 主要改动文件：[文件路径或类名，可列关键项] - 影响面：[受影响的接口、数据表、配置项、上下游调用方] - 是否涉及数据库变更：[是/否，若是说明变更内容与兼容性] - 是否涉及配置或依赖变更：[是/否，若是说明版本与影响] ## 四、验证证据 - 验证方式：[单元测试/集成测试/手工验证/联调] - 验证结果：[通过项与关键结论] - 复现或验证步骤：[评审者可照着复核的步骤] - 补充材料：[截图、录屏、日志、性能对比数据，按需填写] ## 五、风险与回滚 - 主要风险：[可能出问题的场景与影响范围] - 风险等级：[高/中/低，说明判断依据] - 回滚方案：[回滚步骤、是否需要数据修复、回滚后如何验证] - 监控与观察点：[合入后需要关注的指标或日志] ## 六、合入条件 - 前置依赖：[需先合入的改动、需完成的配置或发布动作] - 评审要求：[需哪些角色评审、是否需专项评审] - 合入时机：[是否需避开特定时段、是否需与发布窗口配合] - 待办事项：[合入后需跟进的事项，无则写“无”]
模板保持纯文本形态，不绑定具体平台。团队可以整体复制，也可以按后文的裁剪规则删减选填段落，但六段标题建议保留，便于评审者形成固定的阅读顺序。
字段说明：每个字段回答评审者的哪个问题
模板中的每个字段都对应评审或合入环节的一个具体判断。字段缺失时，评审者只能靠追问补齐信息，评审轮次随之增加。下表按“字段—回答的问题—支撑的判断类型”对照说明。
| 字段 | 回答的问题 | 支撑的判断 |
|---|---|---|
| 变更摘要 | 这次改了什么 | 评审：快速建立改动预期，决定阅读重点 |
| 关联工作项 | 为什么改 | 评审：核对改动是否与需求或缺陷一致；合入：确认工作项状态允许合入 |
| 改动范围与影响面 | 改到哪些模块、谁会受影响 | 评审：确定需要谁参与评审、重点看哪些文件；合入：判断是否需要通知下游或安排联调 |
| 验证方式与结果 | 怎么证明它是对的 | 评审：判断证据是否覆盖改动风险；合入：确认验证已完成 |
| 风险与回滚 | 出问题怎么办 | 评审：评估风险是否可接受；合入：确认回滚路径可用 |
| 合入条件 | 什么时候可以合 | 合入：确认依赖、评审角色与时机均已满足 |
变更摘要与关联工作项共同构成改动的“意图层”：摘要说明动作，工作项说明动机。两者分开写，是因为评审者常需要先看摘要决定是否深入，再用工作项核对范围是否漂移。改动范围与影响面属于“边界层”，它决定了评审的人选和深度，也决定了合入后需要通知哪些协作方。
验证证据是评审中最容易被简化的一项。只写“已自测”无法支撑判断，需要写清验证方式、覆盖了哪些场景、结果如何。风险与回滚则服务于合入决策：风险等级高但回滚方案清晰的改动，与风险不明且无回滚路径的改动，合入判断完全不同。合入条件把分散在评审过程中的前置事项集中列出，避免出现“评审通过但依赖未就绪”的情况。
必填与选填：按改动类型区分填写强度
通用必填项为：变更摘要、关联工作项、改动范围、验证方式与结果、风险与回滚。这五项直接对应评审与合入的核心判断，任何改动类型都不应省略。选填项包括截图或录屏、性能对比数据、评审关注点、依赖变更说明，按改动是否涉及界面、性能、复杂逻辑或外部依赖决定是否填写。
| 改动类型 | 升级为必填的字段 | 填写强度说明 |
|---|---|---|
| 缺陷修复 | 复现步骤、根因说明、回归验证结果 | 需说明缺陷触发条件与修复后回归范围，避免同类问题复发 |
| 新功能 | 关联需求、影响面、评审关注点、截图或录屏 | 需说明功能边界与未覆盖场景，界面类改动附截图 |
| 重构 | 行为不变性说明、回归验证结果 | 需证明对外行为未变，列出重点回归的调用路径 |
| 配置与依赖变更 | 依赖变更说明、兼容性影响、回滚方案 | 需说明版本变化、影响的环境与调用方，回滚需可执行 |
| 紧急修复 | 变更摘要、风险与回滚 | 允许先简化填写以尽快合入，合入后补记关联工作项、验证证据与影响面 |
紧急修复是唯一允许降低填写强度的场景，但简化不等于省略。最低要求是写清改了什么、出问题如何回滚，其余字段在事后补记，补记记录本身也是复盘材料。团队可以把这张表作为评审时的检查依据：字段缺失时，评审者可以直接要求补充，而不是在评论中反复追问。
填写示例：一次缺陷修复的完整合并请求描述
以下示例为演示情景，展示一次缺陷修复如何填满六段式模板。示例中的模块名、编号与数据均为示意，读者可对照替换为自己的实际内容。
## 一、变更摘要 修复订单导出在筛选结果为空时抛出空指针异常的问题，导出空结果时返回带表头的空文件。 ## 二、背景与关联 - 关联工作项：BUG-2317 订单导出空结果报错 - 改动原因：运营在无订单时段导出报表时页面报错，影响日常对账 - 关联文档：无 ## 三、改动范围 - 涉及模块：订单服务 export 模块 - 主要改动文件：OrderExportService.java、OrderExportServiceTest.java - 影响面：仅影响导出接口 /api/order/export，不涉及其他调用方 - 是否涉及数据库变更：否 - 是否涉及配置或依赖变更：否 ## 四、验证证据 - 验证方式：单元测试 + 手工验证 - 验证结果：新增 3 个用例覆盖空结果、单条结果、分页结果，全部通过；手工验证空结果导出返回表头正常的空文件 - 复现或验证步骤：构造筛选条件使结果为空，调用导出接口，检查返回文件 - 补充材料：空结果导出文件截图（略） ## 五、风险与回滚 - 主要风险：导出文件格式变化可能影响下游解析脚本 - 风险等级：低，仅空结果分支行为变化，非空结果逻辑未改动 - 回滚方案：回滚本次提交即可恢复原行为，无数据变更需修复 - 监控与观察点：合入后观察导出接口错误率与文件解析失败日志 ## 六、合入条件 - 前置依赖：无 - 评审要求：订单服务模块负责人评审 - 合入时机：无特殊要求 - 待办事项：通知使用导出文件的对账脚本维护方确认空文件可正常解析
这份示例与字段说明逐项对应：摘要回答改了什么，关联工作项回答为什么改，改动范围界定了影响边界，验证证据给出了可复核的步骤与结果，风险与回滚说明了低风险的依据和回滚路径，合入条件列出了评审角色与合入后的跟进事项。对照必填规则，缺陷修复类型下额外补充了复现步骤与回归验证结果，符合升级要求。
调整与维护：让模板适配团队并长期可用
模板需要按团队实际情况裁剪，而不是原样照搬。小团队或改动粒度较细的项目，可以合并“背景与关联”和“改动范围”中的部分条目，保留关联工作项与影响面两项核心信息；改动类型单一的项目，可以把按类型升级的字段直接写入模板固定段落。裁剪的原则是保留支撑四类判断的字段，删减的是重复表达和低频选填项。
落地方式有两种常见做法。一是把模板保存为仓库中的合并请求模板文件，新建合并请求时自动带出描述框架，评审者看到的结构一致；二是在代码托管平台的项目设置中把模板设为默认描述，适用于多仓库统一管理的团队。两种做法都要求模板文件纳入版本管理，修改时走评审，避免个人随意改动导致字段漂移。
维护节奏可以按季度回看两类信号：评审评论中反复出现的追问，说明某个字段缺失或表述不清；合入后暴露的问题在描述中找不到对应记录，说明风险或验证字段需要加强。把这两类情况整理成修订项，更新模板并通知团队，模板才能持续贴合实际流程。描述本身也应作为流程输入使用：评审时以描述中的验证证据和风险为依据，合入时逐项核对合入条件，形成“描述—评审—合入”的闭环。
当团队使用 ONES 承载研发协作时，合并请求描述中的关联工作项可以与平台内的工作项建立对应关系，评审记录与合入状态围绕同一工作项留存，评审者从工作项即可追溯改动背景、验证结论与合入条件，减少在多个系统间核对信息的动作。模板字段与工作项字段的对应关系确定后，团队可以把描述检查纳入评审流程，让字段填写成为可核验的环节。
常见问题
紧急修复来不及填完整模板，最少要写哪些内容？
紧急修复的最低要求是两项：变更摘要写清这次改了什么，风险与回滚写清可能出问题的场景和回滚步骤。这两项直接决定合入决策者能否放行。关联工作项、验证证据、影响面等字段可以在合入后补记，补记记录同时作为复盘材料。团队应事先约定补记的时限和责任人，避免简化填写变成长期缺省。
评审者反复追问同一个字段，应该改模板还是改评审习惯？
先看追问的性质。如果追问集中在“验证覆盖了哪些场景”“影响哪些调用方”这类信息缺口，说明模板字段表述不够具体，应修订模板中的占位提示语，把要求写得更可操作。如果追问源于评审者习惯逐行确认而不看描述，则需要在评审流程中明确以描述为评审输入。两类情况可以同时处理：模板修订走版本管理，评审习惯通过流程约定逐步统一。
多个仓库共用一套模板时，怎么处理不同技术栈的差异？
建议保留六段标题作为公共骨架，把技术栈相关的内容放进各段内部的可选条目。例如“验证证据”段保留通用的验证方式与结果，前端仓库可增加截图要求，后端仓库可增加接口兼容性说明。公共骨架保证评审者阅读顺序一致，仓库级差异通过模板文件的分支或目录级配置维护。改动公共骨架时统一评审，仓库级条目由各仓库负责人维护。
合并请求描述和关联工作项里的信息重复，是否只需写一处？
两处承担的作用不同。工作项记录需求或缺陷的完整背景与状态流转，合并请求描述面向本次改动的评审者，需要把与这次改动直接相关的动机、范围和验证结论集中呈现。建议描述中写关联工作项编号，并用一两句话概括改动动机，详细背景链接到工作项，避免评审者在两个系统间来回查找。这样既减少重复，也保证描述单独阅读时信息完整。
模板落地后如何判断它是否真的在起作用？
可以观察三类信号：评审评论中与改动信息相关的追问是否减少；因描述缺失导致的评审退回或补充提交是否下降；合入后出现的问题能否在描述的风险与验证段落中找到对应记录。前两类反映描述的信息完整度，第三类反映字段设计是否贴合实际风险。按季度汇总这些信号，形成具体的修订项，比单纯统计填写率更能说明模板的效果。
