制定版本命名规范，核心是先确定一套可解析的版本号结构，再把它写成团队能执行的规则：版本号由哪几段组成、每段在什么条件下递增、预发布与构建信息如何标识、谁批准版本号变更，最后把规则落到发布流程和版本记录里。本文按“定结构—写文档—明角色—试运行—持续维护”的顺序，给出一份可直接评审和落地的规范草案。
要点总览（TL;DR）
- 先以语义化版本的“主版本.次版本.修订号”为骨架，再补充预发布标识与构建元数据的内部约定，让版本号本身能表达兼容性变化。
- 规范文档要写清格式定义、递增规则、正反例对照、例外处理和变更管理五类条目，判断标准是新人只看文档就能正确编号。
- 把版本号确定人、审核人和发布执行人的职责绑定到发布流程节点，版本号在提测前冻结，并与发布记录、变更记录关联。
- 规范上线后设置两到三个发布周期的试运行期，用发布前检查清单逐项核对，再按固定节奏复审修订。
- 已发布的版本号不再修改，通过下一个修订号修正；未发布的版本号可直接更正并留下更正痕迹。
先定版本号结构：主版本、次版本、修订号与预发布标识
版本号结构是整份规范的地基。建议以语义化版本（SemVer）的“主版本.次版本.修订号”作为骨架，再补充团队内部的预发布与构建标识约定。这样做的价值在于：版本号本身能表达兼容性变化，研发、测试、运维和客户支持看到编号就能判断这次发布的性质，无需额外解释。
字段定义需要写清三件事：每段代表什么、在什么条件下递增、给出一个示例。下表可作为规范文档的第一张表直接使用。
| 字段 | 含义 | 递增条件 | 示例 |
|---|---|---|---|
| 主版本号 | 标识不兼容的对外变更 | 接口、数据格式或使用方式发生不兼容调整时递增，其余段归零 | 2.0.0 |
| 次版本号 | 标识向后兼容的功能新增 | 新增功能且不影响既有调用方时递增，修订号归零 | 2.3.0 |
| 修订号 | 标识向后兼容的问题修复 | 仅修复缺陷、调整文案或性能优化时递增 | 2.3.4 |
| 预发布标识 | 标识尚未正式发布的候选版本 | 进入测试、灰度或候选阶段时追加，正式发布时移除 | 2.4.0-rc.1 |
| 构建元数据 | 标识同一次构建的来源信息 | 每次构建可追加，不参与版本先后比较 | 2.4.0-rc.1+build.52 |
预发布标识与构建元数据是否进入正式版本号，需要在规范中明确表态。常见做法是：预发布标识只出现在候选版本上，正式发布时去掉；构建元数据仅用于内部追溯，不进入对外公布的版本号。这样对外版本号保持简洁，内部仍能定位到具体构建。
避免同一版本号对应多个制品，是结构设计必须回答的问题。可行做法包括：规定一个版本号只能指向一个通过验收的制品；重新构建必须递增修订号或追加新的预发布序号；禁止在已发布版本上覆盖重新打包。把这条写成硬性规则，能减少后续追溯时的歧义。
把规则写成可执行文档：命名格式、示例与例外约定
结构确定后，需要把它写成一份可评审、可引用的规范文档。文档的目标读者是新加入的研发、测试和发布人员，判断标准是：只看文档能否正确编出一个版本号。因此文档应包含格式定义、递增规则、正反例对照、例外处理和变更管理五类条目。
正例与反例对照是最有效的写法。每条规则配一个正确示例和一个错误示例，并说明错在哪里，比单纯描述规则更容易被记住。例如“2.4.0-rc.1”是正确写法，“2.4.0rc1”缺少分隔符、“v2.4”缺少修订号，都属于不符合格式约定的写法。
| 对照项 | 正例 | 反例 | 问题说明 |
|---|---|---|---|
| 完整格式 | 2.4.0 | 2.4 | 缺少修订号，无法区分修复版本 |
| 预发布写法 | 2.4.0-rc.1 | 2.4.0rc1 | 缺少连字符与点号分隔，解析困难 |
| 递增位置 | 2.4.1 | 2.5.0 | 仅修复缺陷却递增次版本号，语义不符 |
| 前缀约定 | release-2.4.0 | release2.4 | 标签名与版本号格式不一致 |
分支名、标签名、发布说明标题与版本号需要建立对应关系，否则同一版本在不同位置会出现不同写法。建议规定：发布标签统一采用“release-主版本.次版本.修订号”格式；发布说明标题以版本号开头；长期维护分支以主版本号命名。把这些对应关系写进文档，评审时就能逐项核对。
例外处理同样要写清楚。例如紧急热修复、客户定制版本、内部试验版本，可能无法完全套用标准格式。规范应给出受限的例外写法，并规定例外必须记录原因和批准人。规则变更由发布负责人提出、技术负责人批准，变更后更新文档版本号并通知所有发布相关角色。
角色分工与执行机制：谁编号、谁审核、谁发布
规范停留在文档层面，最常见的原因是没有人对版本号负责。落地时需要明确三个角色：版本号确定人、审核人和发布执行人，并把版本号的冻结绑定到发布流程的具体节点。
| 角色 | 职责 | 关键节点 |
|---|---|---|
| 版本号确定人（通常为发布经理或配置管理员） | 根据本次变更内容确定版本号，填写版本记录 | 发布计划确认时给出初稿，提测前冻结 |
| 审核人（技术负责人或模块负责人） | 核对递增规则是否符合变更性质，检查格式与唯一性 | 版本号冻结前完成审核 |
| 发布执行人 | 按冻结的版本号打标签、生成制品、撰写发布说明 | 发布执行与发布后记录 |
版本号冻结节点建议设在提测或发布候选构建之前。冻结之后如需调整，必须走变更记录，说明原因并经审核人确认。版本号与发布记录、变更记录的关联方式也要规定：每条发布记录包含版本号、变更清单、审核人和发布时间；每个变更项标注它影响了主版本、次版本还是修订号。这样版本号的递增依据可以回溯到具体变更。
发现编号错误时，处理原则是“已发布不改号，未发布可纠正”。已经对外发布的版本号不再修改，通过下一个修订号修正并在发布说明中注明；尚未发布的版本号可以直接更正，但需在记录中留下更正痕迹。追溯时以发布记录中的版本号为准，避免多处口径不一致。
在版本号确定与发布记录关联这一管理动作上，ONES 可以承载版本记录与变更项的关联，让版本号、变更清单和审核信息保存在同一处，便于发布后追溯。具体使用方式按团队现有流程配置即可。
示例：一条完整版本从开发到发布的编号过程
下面用两个情景演示规则如何被使用。示例为演示情景，用于说明编号逻辑，不代表任何真实项目。
情景一：功能发布。某服务当前版本为 2.3.4。本次迭代新增了一个查询接口，既有调用方式不受影响。输入是变更清单，动作是判断变更性质为向后兼容的功能新增，输出是次版本号递增、修订号归零，版本号定为 2.4.0。进入测试阶段时追加预发布标识，形成 2.4.0-rc.1；测试通过后去掉预发布标识，正式发布 2.4.0。发布说明标题写“2.4.0 发布说明”，标签名为 release-2.4.0，制品标识与版本号一致。
情景二：缺陷修复发布。2.4.0 发布后发现一个影响部分用户的缺陷。输入是缺陷单与影响范围说明，动作是判断该修复不改变接口和功能范围，输出是修订号递增，版本号定为 2.4.1。由于修复紧急，直接发布正式版本，不经过预发布阶段；发布说明中注明修复内容与影响范围，标签名为 release-2.4.1。
两个情景的差异集中在递增位置：功能新增走次版本号，缺陷修复走修订号。预发布到正式版本的过渡则体现为“追加标识—验证—移除标识”的过程。把这两个情景写进规范文档作为附录，新成员对照即可完成大多数编号判断。
上线前检查与持续维护：规范是否真的被执行
规范发布后，需要用检查清单验证执行情况。建议在每次发布前逐项核对，全部通过才允许发布。
- 版本号格式符合规范，各段齐全，分隔符正确。
- 递增位置与本次变更性质一致，并在变更记录中注明依据。
- 版本号在团队内唯一，未与历史版本重复。
- 预发布标识仅在候选版本出现，正式版本已移除。
- 标签名、发布说明标题、制品标识与版本号一致。
- 审核人已确认，发布记录已关联变更清单。
规范上线后建议设置一个试运行期，例如覆盖两到三个发布周期。观察点包括：编号判断是否频繁需要讨论、例外情况出现频率、检查清单是否有条目被反复跳过。试运行结束后汇总问题，集中修订一次规则，避免边用边改导致口径混乱。
常见问题需要预设处理方式。版本号冲突时，以发布记录中先登记的为准，后登记者递增修订号；跳号不影响正确性，但应在记录中说明原因；重复版本号对应不同制品属于严重问题，必须停止发布并追溯来源。规范本身也应版本化维护，建议每半年或发布流程发生较大调整时复审一次，复审结论和修订内容记入文档变更历史。
常见问题
团队规模很小，还需要单独设版本号审核人吗？
审核环节的价值在于核对递增位置是否与变更性质一致，与团队规模关系不大。小团队可以让技术负责人兼任审核人，但建议保留“确定”和“审核”两个动作，哪怕由不同的人在不同时间完成。如果确定人和审核人是同一人，至少要在发布记录中写明递增依据，便于事后回溯。团队规模扩大后再拆分角色，规则本身不需要重写。
紧急热修复来不及走预发布流程，版本号怎么处理？
热修复通常直接递增修订号并发布正式版本，例如从 2.4.0 到 2.4.1，跳过预发布阶段。规范中应把这种情况写成受限例外：允许省略预发布标识，但必须在发布记录中注明“紧急修复”、影响范围和批准人。如果修复本身改变了接口或使用方式，仍应按不兼容变更处理，递增主版本号，不能因为紧急就降级处理。
长期维护多个历史版本时，版本号如何避免冲突？
常见做法是让长期维护分支以主版本号命名，各分支只在自己的主版本号下递增次版本号和修订号。例如 2.x 维护分支发布 2.5.1，3.x 主线发布 3.2.0，两者互不干扰。规范中要写明分支与版本号的对应关系，并在发布记录中标注所属主版本线。这样即使同时维护多个版本，版本号仍然全局唯一。
规范试运行期间发现规则不合理，可以边用边改吗？
建议把试运行期内的修改集中处理，避免频繁变更导致口径混乱。试运行期间记录每次编号判断需要讨论的情况、例外出现的频率，以及检查清单中被反复跳过的条目。试运行结束后统一修订一次规则，更新文档版本号并通知所有发布相关角色。试运行期内确需临时调整的，按例外处理并记录原因。
版本号已经对外发布，后来发现编号错了怎么办？
处理原则是已发布不改号。已经对外公布的版本号保持不变，通过下一个修订号发布修正版本，并在发布说明中注明前一版本号存在的问题。如果错误影响客户对版本性质的理解，例如把不兼容变更错标为修订号，应在下一个版本中按正确的主版本号递增，并在发布说明中说明版本号跳跃的原因。追溯时以发布记录中的版本号为准。
