分支名里没有工作项编号、提交信息里的编号写错一位、一个分支同时挂着几个工作项，这些问题会让代码变更与需求、缺陷的对应关系变得模糊。本文以演示情景给出一套可直接套用的分支工作项关联规则，包含分支命名模板、提交信息模板、状态约定与校验清单，并逐项说明字段取值理由和换团队时的调整方式。
要点总览（TL;DR）
- 分支工作项关联规则由三部分组成：分支命名模板、提交信息模板和校验动作，三者共同保证代码变更能挂到具体工作项上。
- 分支名采用“类型/工作项编号-简短描述”，提交信息采用“类型(工作项编号): 改动说明”，编号必须与工作项系统中的完整编号一致。
- 工作项状态在创建分支、发起合并请求、合并主干三个节点流转，校验放在推送时和合并前成本最低。
- 换团队时调整编号来源、仓库标识和校验方式即可，规则结构保持不变；先小范围试运行再全团队执行。
- 规则只覆盖代码与工作项的对应关系，代码库接入、评审合入规则和工作项拆分质量不在其范围内。
示例要解决什么问题：分支与工作项对不上
本文的规则示例设定为一个演示情景：一个约二十人的研发团队，使用统一的工作项编号体系（如需求 REQ-1024、缺陷 BUG-2077），代码托管在同一个主仓库，日常通过分支开发、合并主干的方式交付。示例中的编号、分支名和提交信息均为演示值，不指向任何真实客户或实测结果。
在这个情景里，团队遇到的失配现象主要有三类。第一类是分支名不带编号，开发人员建了 fix-login 这样的分支，事后只能靠记忆或聊天记录回溯它对应哪个工作项。第二类是提交信息里的编号写错或写漏，比如工作项是 BUG-2077，提交里写成 BUG-207 或 BUG-2700，追溯时匹配不上。第三类是一个分支挂多个工作项，开发顺手把两个需求的改动放进同一分支，合并后无法判断哪部分代码属于哪个工作项。
规则要达成的结果可以归纳为三条：
- 可追溯：从任意一个工作项出发，能找到与它相关的分支和提交；从任意一个分支出发，能说清它服务于哪个工作项。
- 可校验：编号格式有明确约束，人和工具都能快速判断对错，而不是靠人工逐个核对。
- 可交接：人员轮换、任务转交时，接手人通过分支名和提交信息就能理解上下文，不需要额外询问。
这三条结果决定了规则不能只写一句“分支要带编号”，而要同时约定格式、写入时点和检查动作。
完整示例：一套分支工作项关联规则
以下规则文本按“命名—提交—状态—校验—异常”五部分组织，可以直接复制到团队的研发规范文档中，替换示例值后使用。
分支命名模板
模板：{类型}/{工作项编号}-{简短描述}
- 类型取值：
feature（需求）、bugfix（缺陷）、hotfix（线上紧急修复）、refactor（重构）、chore（构建与杂项）。 - 工作项编号：沿用工作项系统中的完整编号，含前缀，如
REQ-1024、BUG-2077。 - 简短描述：小写英文或拼音，单词间用连字符，控制在 30 个字符以内，只描述改动内容，不重复编号。
示例值：
feature/REQ-1024-order-exportbugfix/BUG-2077-login-timeouthotfix/BUG-2101-payment-callback
提交信息模板
模板：{类型}({工作项编号}): {改动说明}
示例值：
feat(REQ-1024): 增加订单导出接口与分页参数fix(BUG-2077): 修正登录超时后会话未清理的问题hotfix(BUG-2101): 修复支付回调重复处理的边界情况
约定提交信息首行不超过 72 个字符，编号必须与分支名中的编号一致；一次提交只对应一个工作项，涉及多个工作项的改动应拆分为多次提交或拆分分支。
工作项状态与分支生命周期的对应约定
| 分支动作 | 工作项状态 | 责任人 |
|---|---|---|
| 创建分支 | 工作项置为“进行中”，并记录分支名 | 开发人员 |
| 提交代码并推送 | 状态保持“进行中”，提交信息自动关联 | 开发人员 |
| 发起合并请求 | 工作项置为“待评审”，附合并请求链接 | 开发人员 |
| 合并入主干 | 工作项置为“待验证”或“已完成”，按团队验收口径确定 | 评审人或测试人员 |
| 分支删除 | 确认工作项已关闭或已转交，避免悬空 | 开发人员 |
校验动作与责任人
- 提交前自检：开发人员在本地确认分支名与提交信息中的编号一致，由提交模板或本地钩子提示格式。
- 推送时校验：仓库侧配置分支命名与提交信息的格式检查，不符合规则的分支或提交被拒绝，责任人为仓库管理员配置、开发人员执行。
- 合并前复核：评审人检查合并请求对应的分支名、提交信息与工作项是否一致，发现不一致退回修改。
- 周期性抽查：团队负责人每两周抽查一次分支与工作项的对应情况，记录偏差并反馈到规范中。
异常情况的处理写法
热修复：从主干拉出 hotfix/{编号}-{描述} 分支，提交信息同样带编号；修复完成后先合并主干再合并发布分支，工作项状态在合并主干后更新。紧急回滚：回滚提交的信息写为 revert({工作项编号}): 回滚{原提交说明}，并在对应工作项下补充回滚原因与影响范围，避免回滚动作脱离工作项记录。对于确实无法提前建工作项的线上故障，允许先建分支后补编号，但须在 24 小时内补齐工作项并在分支描述中注明。
逐项解释：每个字段为什么这样定
规则中的每个字段都对应一个具体的追溯或校验需求，理解取值理由后，替换成自己团队的写法才有依据。
| 字段或约定 | 取值理由 | 替换方式 |
|---|---|---|
| 工作项编号放在分支名前缀之后 | 分支列表通常按名称排序，编号靠前便于按工作项检索；同时避免描述词干扰编号识别 | 若团队习惯按人员或模块分组，可在编号前加模块前缀，但编号位置保持固定 |
| 类型前缀与工作项类型对应 | 分支列表一眼能区分需求、缺陷与紧急修复，便于安排评审优先级 | 类型取值可增减，但需与工作项类型保持一一映射，避免同一含义多种写法 |
| 提交信息中编号放在括号内、紧跟类型 | 固定位置便于工具解析和人工扫读，括号把编号与说明文字分隔开 | 可改为方括号或冒号分隔，关键是全团队统一且工具能识别 |
| 状态随分支创建、合并请求、合并主干三个节点流转 | 这三个节点是代码进展的客观信号，状态更新有明确触发点，减少手工维护 | 若团队有独立测试环节，可在合并主干后增加“测试中”状态 |
| 校验放在推送时与合并前 | 推送时拦截成本最低，问题在进入主干前暴露；合并前复核覆盖语义一致性 | 小团队可先只做合并前人工复核，规模扩大后再加自动校验 |
关于编号位置，还有一个实际考虑：分支名在合并请求、代码对比、构建记录等多个界面反复出现，编号越靠前，被截断的概率越低。关于状态流转，约定的是“谁在什么时点改状态”，而不是要求状态与代码完全同步，这样开发人员不必为每次提交都更新工作项。
校验动作放在推送环节最省成本，原因是此时改动尚未进入主干，修正只需重命名分支或修改提交信息；一旦合并后再发现编号错误，追溯链已经断裂，修复成本明显上升。
可迁移规律：换团队、换工具怎么改
这套示例背后的规律可以概括为：编号是关联的锚点，格式是校验的前提，时点是状态的触发器。换团队时，调整的是这三者的具体取值，而不是推翻结构。
- 编号体系变化：如果团队使用“项目缩写+序号”的编号，模板中的编号段整体替换即可，分支名与提交信息中的编号必须来自同一来源，避免手工输入造成偏差。
- 单仓库与多仓库：单仓库场景下分支名唯一即可定位；多仓库场景需要在分支名或提交信息中补充仓库或服务标识，否则同一编号在不同仓库出现时无法区分，建议在描述段前加服务名。
- 人工校验与自动校验的取舍：团队人数少、提交频率低时，合并前人工复核即可满足追溯需求；提交频率上升后，推送时的格式检查能显著减少返工，自动校验的规则应与人工复核口径一致。
- 推进节奏：建议先在一个小组试运行两到四周，收集分支命名和提交信息的实际偏差，修订模板后再全团队执行；正式执行时保留一个过渡期，对历史分支不做追溯要求。
在工具层面，分支与工作项的关联最终要落到可查询的记录上。ONES 的工作项管理可以承载需求、缺陷等工作项，团队在分支名和提交信息中写入工作项编号后，可以在工作项下记录对应的分支与合并请求信息，便于后续按工作项查看代码进展和交接上下文。具体关联方式与状态同步能力，建议在选型或配置时结合团队使用的代码托管工具确认。
适用边界：这套规则管不到的地方
这套规则覆盖的范围是代码变更与业务工作项之间的对应关系，即通过分支名和提交信息把代码改动挂到具体工作项上。它不涉及代码库的接入方式与权限配置，这部分属于研发工具链集成的范畴；也不规定代码评审的检查项、合入条件与分支保护策略，这些属于代码评审与合入管理主题。
规则本身也无法替代工作项的拆分质量。如果一个工作项范围过大、描述含糊，即使分支名和提交信息格式完全正确，追溯到的也只是一个笼统的任务，无法说明具体改了什么。规则能保证“挂得上”，挂得准不准取决于工作项本身的粒度与描述。此外，规则对跨团队协作中的编号冲突、历史遗留分支的追溯不提供解决方案，这些需要在执行中另行约定。
常见问题
线上紧急故障来不及先建工作项，分支怎么命名？
允许先建分支后补编号。分支仍按 hotfix/{编号}-{描述} 的格式创建，如果编号尚未生成，可先用临时占位并在分支描述中注明故障现象，但须在 24 小时内补齐工作项，把分支名和提交信息中的占位替换为正式编号。补编号时同步检查已推送的提交信息，必要时用补充提交说明关联关系，避免追溯链断开。
一个改动同时涉及需求和缺陷两个工作项，应该拆分支还是拆提交？
优先拆分支。一个分支对应一个工作项，能让合并请求、代码对比和状态流转都指向唯一对象。如果两个工作项的改动确实耦合、无法分开验证，可以保留一个分支，但提交信息要按工作项分别书写，并在合并请求描述中说明两个工作项的对应关系。无论哪种方式，都要避免一个提交里混入多个工作项的改动，否则后续按工作项追溯时无法切分。
团队已经在用的历史分支没有编号，需要全部改名吗？
不需要。规则正式执行时保留过渡期，对已合并或已关闭的历史分支不做追溯要求，只对执行日期之后新建的分支生效。仍在开发中的历史分支，可以在下一次推送时补充提交信息中的工作项编号，分支名保持不变并在分支描述中注明对应工作项。这样既避免大规模改名带来的协作中断，也让活跃分支逐步纳入规则。
自动校验会不会误拦正常提交，怎么减少误报？
误报通常来自规则过严或格式约定不统一。建议先明确编号来源，让分支名和提交信息中的编号都从工作项系统复制，减少手工输入偏差；格式检查只校验编号是否存在、是否与分支一致，描述文字的长度和用词放宽。上线初期可以把检查设为提醒而非拒绝，观察一到两周的实际拦截记录，再调整为强制拦截，规则口径与合并前人工复核保持一致。
多仓库场景下，同一个工作项在多个仓库都有改动，怎么区分？
在分支名的描述段前加服务名或仓库标识，例如 feature/REQ-1024-order-service-export，让同一编号在不同仓库的分支可以区分。提交信息中保持编号位置不变，仓库信息由代码托管平台自身记录。合并请求描述里列出该工作项涉及的全部仓库和分支，便于评审人核对改动范围是否完整。
