制定代码提交关联规范，核心是先把三件事写清楚：提交信息里写什么、关联到哪个工作项、由谁在什么时点校验。规范篇幅控制在一到两页，先覆盖主干流程，再补充例外条款，让开发者能照着做、评审者能照着查。本文按要素、步骤、角色、示例和校验顺序展开，聚焦代码变更与业务工作项的对应关系，代码库接入配置和评审合入的具体规则不在本文范围。
要点总览（TL;DR）
- 一份可执行的代码提交关联规范至少写清四类要素：提交信息格式、工作项编号来源与唯一性、关联动作发生的环节、校验点由谁以什么方式执行。
- 制定按五步推进：盘点现有提交习惯与工作项体系、设计提交信息模板与编号引用规则、确定分支命名与提交粒度、起草规范文本、试运行后修订定稿，篇幅控制在一到两页。
- 开发者负责提交时引用正确编号，评审者核对编号与变更内容是否匹配，测试与发布人员从工作项反查提交记录，规范维护者负责抽样审计与修订。
- 校验靠三层机制：提交时的格式检查、评审与合入时的关联门禁、每两周或每月的抽样审计；门禁严格程度可随团队成熟度从提醒逐步过渡到拦截。
- 规范可用的判断标准是六项自查全部为“是”，其中追溯可用一项要求随机选一个工作项能查到对应提交、随机选一个提交能找到对应工作项。
规范先定哪几件事：提交信息、关联对象与校验点
一份可执行的关联规范，最小构成是四类要素。缺任何一类，规范都会退化成“请大家写清楚提交信息”的倡议。
提交信息格式。需要规定类型、范围、摘要和工作项编号的位置。常见结构是“类型(范围): 摘要”加正文或尾行的工作项编号，例如“feat(order): 支持批量取消订单”后接“关联: ORDER-2317”。类型取值（如 feat、fix、refactor、docs）要在规范里列全，避免各人自造；范围写模块或服务名；摘要用一句话说明改了什么，不写“修改代码”“优化逻辑”这类无信息量的表述。工作项编号放在固定位置，便于人工阅读和工具提取。
工作项编号的来源与唯一性。编号必须来自团队既有的需求、缺陷或任务编号体系，规范中写明从哪个系统取号、在哪个字段引用。禁止开发者自造编号或引用已关闭的旧编号。一个提交原则上关联一个主工作项；确实涉及多个工作项时，写明主关联项，其余在正文列出，避免一条提交挂五六个编号导致追溯失真。
关联动作发生的环节。要明确关联是在提交时完成、评审时补齐，还是合入前必须完成。推荐把关联作为提交时的动作，评审时只做检查，合入前作为门禁。这样责任落在提交者身上，评审者不必替人补编号。
校验点与执行方式。每个校验点写清由谁执行、以什么方式执行、不通过怎么处理。提交时可由提交信息模板或钩子做格式检查；评审时由评审者核对编号与变更内容是否匹配；合入时由门禁拦截缺失关联的提交；周期性由规范维护者抽样审计。自动或人工取决于团队工具条件，规范里要写明当前采用哪一种。
分步制定：从字段设计到规范定稿
制定过程按五步推进，每步都有明确输入和完成标志，避免写到一半发现与现有习惯冲突。
| 步骤 | 输入 | 动作 | 输出 | 完成标志 |
|---|---|---|---|---|
| 1. 盘点现状 | 近三个月提交记录、工作项编号体系、现有分支命名 | 统计提交信息中带编号的比例、常见写法、缺失场景；确认编号从哪个系统产生 | 现状盘点记录，列出主要偏差类型 | 能说出当前关联率与三类典型问题 |
| 2. 设计模板与引用规则 | 现状盘点记录、团队使用的代码托管平台 | 确定提交信息结构、类型取值、编号引用位置；确定编号缺失时的处理方式 | 提交信息模板与编号引用规则 | 模板能套用到最近十条真实提交上 |
| 3. 确定分支命名与提交粒度 | 现有分支习惯、发布节奏 | 规定分支名包含工作项编号或需求简称；规定一个提交对应一个可描述的变更单元 | 分支命名规则与提交粒度说明 | 规则能覆盖主干、修复、紧急发布三类分支 |
| 4. 起草规范文本 | 前三步产出 | 按要素清单写成短文档，写明生效范围、生效时间、例外申请方式 | 规范初稿，一至两页 | 初稿覆盖四类要素且无待定项 |
| 5. 试运行与定稿 | 规范初稿、一个迭代或两周的试运行数据 | 在小范围团队试运行，收集格式歧义与执行阻力，修订后发布 | 定稿版本与修订记录 | 试运行期关联率达到约定目标，歧义条款已改写 |
试运行阶段重点观察两类问题：一是模板字段在实际提交中是否够用，二是校验点是否造成不必要的阻塞。发现某类紧急修复难以在提交时拿到编号，就在规范中补充“先提交、二十四小时内补关联”的例外条款，并写明补录责任人和检查方式，而不是让例外停留在口头默契。
角色分工与各环节交付物
规范只约束开发者、无人校验，是最常见的失效原因。下表把每个角色的动作和交付物固定下来，便于认领和检查。
| 角色 | 环节 | 动作 | 交付物 |
|---|---|---|---|
| 开发者 | 提交 | 按模板写提交信息，引用正确的工作项编号；分支名带编号或需求简称；一个提交对应一个变更单元 | 符合格式的提交记录与分支 |
| 评审者 | 代码评审 | 核对提交信息中的编号是否存在、是否与变更内容匹配；缺失或错挂时要求提交者修正后再评审 | 评审意见中的关联检查结论 |
| 测试人员 | 验证 | 从工作项出发查看关联提交，确认变更范围与提测内容一致；发现未关联的变更时反馈给开发补录 | 提测范围与提交记录的对照结论 |
| 发布负责人 | 发布 | 按工作项汇总本次发布包含的变更，核对是否有未关联提交混入 | 发布清单与工作项的对应关系 |
| 规范维护者 | 周期 | 抽样审计关联质量，收集执行问题，按季度或按需修订规范 | 审计记录与规范修订版本 |
角色分工要落到具体人，而不是岗位名称。小团队可以一人兼多个角色，但每个环节的检查动作不能省。当工作项和代码提交记录在同一平台管理时，追溯会省力很多：开发者在工作项上推进状态，提交时引用编号，工作项侧即可看到关联的提交记录，测试和发布人员从工作项直接查到变更，不必在多个系统间手工比对。ONES 支持工作项与代码提交记录的关联展示，具体配置方式与校验能力建议在选型或部署时向官方确认，本文不展开产品配置细节。
提交信息与关联字段示例
下面是一条符合规范的提交信息，逐段说明各部分的写法。
fix(payment): 修复退款金额四舍五入误差 退款计算改为按分取整，避免出现 0.01 元差额。 影响范围：退款申请、部分退款。 关联: PAY-1042
首行“fix(payment): 修复退款金额四舍五入误差”中，fix 是类型，payment 是范围，冒号后是摘要，说明改了什么、影响哪个功能。空行后的正文解释原因和影响范围，帮助评审者判断变更边界。末行“关联: PAY-1042”是工作项编号，位置固定，便于人工和工具识别。
分支命名示例：“fix/PAY-1042-refund-rounding”，包含类型、编号和简短描述；“feature/ORDER-2317-batch-cancel”同理。紧急修复可用“hotfix/PAY-1042”，编号仍不可省。
工作项侧的记录方式：在 PAY-1042 的详情中能看到关联的提交记录、提交人和时间，测试人员据此确认修复已进入哪个分支、是否已合入主干。关联记录应包含提交哈希或链接、分支和状态，便于从工作项反查代码。
常见错误写法与修正：
- “修改bug”——缺少类型、范围、编号，无法追溯。修正为“fix(order): 修复订单列表分页越界，关联: ORDER-2317”。
- “feat: 若干优化，关联: ORDER-2317, ORDER-2318, ORDER-2319”——一条提交挂多个编号，追溯失真。修正为拆分为多个提交，或只保留主关联项，其余在正文说明。
- 引用已关闭或不存在的工作项编号——评审时核对编号状态，发现后要求改为有效编号。
- 分支名写“dev”“test1”——无法对应需求。修正为带编号的命名。
落地校验：检查项、门禁与抽样审计
规范是否被执行，靠三层校验来验证，每层都有明确的执行时点和处理方式。
| 检查项 | 执行时点 | 负责人 | 处理方式 |
|---|---|---|---|
| 提交信息格式与编号是否存在 | 提交时 | 提交者；条件允许时由钩子或模板自动检查 | 格式不符时提示修正；编号缺失时要求补录 |
| 编号与变更内容是否匹配 | 代码评审 | 评审者 | 不匹配时退回修改，评审不通过 |
| 关联完整性门禁 | 合入主干前 | 合入操作人；条件允许时由平台规则拦截 | 缺失关联的提交不允许合入，紧急情况走例外流程并登记 |
| 抽样审计 | 每两周或每月 | 规范维护者 | 随机抽取若干提交与工作项，核对关联真实性；偏差记入审计记录 |
| 偏差处理与迭代 | 审计后 | 规范维护者 | 同类偏差出现三次以上，评估是规范条款问题还是执行问题，修订规范或加强提醒 |
抽样审计的样本建议覆盖不同类型：功能提交、缺陷修复、紧急发布各抽若干条，重点看编号是否真实对应、变更范围是否与工作项描述一致。审计结果不必公开排名，但要形成记录，作为规范修订的依据。门禁的严格程度可以随团队成熟度调整：初期以提醒为主，关联率稳定后再改为拦截，避免一开始就造成大量阻塞。
完成检查：规范可用的判断标准
规范定稿前，用下面这份自查表逐项确认。每项都能给出明确的是或否，而不是“基本可以”。
| 检查项 | 判断标准 | 结果 |
|---|---|---|
| 要素覆盖 | 提交信息格式、编号来源、关联环节、校验点四类要素均有明确条款 | 是 / 否 |
| 试运行与修订 | 经过至少一个迭代或两周试运行，歧义条款已改写，修订记录可查 | 是 / 否 |
| 角色认领 | 开发者、评审者、测试、发布、维护者五个角色的动作均有具体人认领 | 是 / 否 |
| 校验配置 | 提交检查、评审检查、合入门禁至少两层已配置并实际运行过 | 是 / 否 |
| 追溯可用 | 随机选一个工作项，能查到对应提交；随机选一个提交，能找到对应工作项 | 是 / 否 |
| 例外条款 | 紧急修复等例外场景有书面流程和补录时限 | 是 / 否 |
六项全部为“是”，规范才算可用。若追溯可用一项为否，说明关联记录没有真正建立，需要回到校验环节检查门禁是否生效。规范发布后，建议在下一个迭代结束时再复查一次关联率，确认执行没有回落，再进入常规审计节奏。
常见问题
团队提交信息里已经习惯写需求编号，还需要单独制定规范吗？
需要，但重点可以放在补齐缺失的部分。已有写编号的习惯说明基础不错，规范要解决的是写法不统一和校验缺位：编号放在哪个位置、类型和范围怎么取值、一条提交关联多个工作项时怎么处理、编号缺失或写错由谁在哪个环节拦下。把这些写成条款，评审者才有依据检查，审计时也才有对照标准。
紧急修复来不及先建工作项，规范应该怎么处理？
在规范中写明例外流程，而不是靠口头默契。常见做法是允许先提交、在约定时限内（如二十四小时）补建或补关联工作项，同时写明补录责任人和检查方式，例如由发布负责人在发布清单核对时确认补录已完成。例外条款要限定适用场景，并纳入抽样审计范围，避免例外变成常态。
关联门禁一开始就设成拦截，会不会影响交付节奏？
可以分阶段设置。试运行期以提醒和评审检查为主，观察关联率与阻塞情况；关联率稳定后再把合入前的门禁改为拦截。若直接拦截，建议同时明确紧急情况的放行方式与登记要求，让被拦下的提交有明确处理路径，减少对发布节奏的影响。
一个提交涉及多个工作项时，规范要求怎么关联？
原则上一条提交关联一个主工作项，其余工作项在提交信息正文中列出。这样追溯时不会因为一条提交挂多个编号而失真。如果变更确实跨越多个独立需求，更合适的做法是拆分为多个提交，每个提交对应一个可描述的变更单元，再分别关联。
规范发布后关联率回落，应该先改规范还是先加强检查？
先看偏差类型。抽样审计中同类偏差反复出现，要判断是条款本身难执行还是执行意愿问题：条款歧义或字段不够用，就修订规范；条款清晰但执行不到位，就加强提醒与检查频次。规范维护者可按季度或按需修订，并把审计记录作为修订依据。
