版本命名规范的核心是给版本号定一套可解析的结构：主版本、次版本、修订号分别对应不兼容变更、向下兼容的功能新增和缺陷修复，再按需附加预发布标识与构建元数据。本文给出字段定义、编写步骤、角色分工和完成检查，帮助团队写出能被一致执行、可机器校验的规范条文。
要点总览（TL;DR）
- 版本号采用主版本.次版本.修订号三段结构，分别对应不兼容变更、向下兼容的功能新增和缺陷修复，按需追加预发布标识与构建元数据。
- 递增规则写成判断顺序：不兼容变更进主版本并归零后两位，功能新增进次版本并归零修订号，仅修缺陷进修订号；同批次按最高级别变更进位。
- 版本号在提测时申请、发布评审通过后冻结，由版本管理员维护台账，研发、测试、发布负责人分别确认变更性质、测试结论和发布记录。
- 落地分四步：盘点现状、确定结构并写正反示例、定义分配与冻结时点、小范围试行并回放历史版本。
- 用可机器解析、历史版本回放、发布记录一一对应、新成员独立编写四项检查判断规范是否真正执行，违规时登记更正并补规则缺口。
版本命名规范先定哪几个字段
写规范的第一步是把版本号拆成固定字段，并给每个字段写明含义、取值格式和递增条件。字段一旦确定，版本号就有了可比较、可排序的基础，后续的审核与校验才有依据。建议以三段数字结构为骨架，按需附加两段可选标识。
三段结构的语义分工
主版本、次版本、修订号三段分别承载不同性质的变更，团队在判断“这次该进哪一位”时，只需回答变更是否破坏兼容性、是否新增功能、是否只修缺陷三个问题。
| 字段名 | 含义 | 取值格式 | 递增触发条件 | 示例 |
|---|---|---|---|---|
| 主版本号 | 标识不兼容的对外变更 | 非负整数，从 0 或 1 起 | 接口签名、数据格式、配置项、行为语义发生不兼容调整 | 2.0.0 |
| 次版本号 | 标识向下兼容的功能新增 | 非负整数 | 新增接口、新增可选参数、新增能力，旧用法仍可用 | 2.3.0 |
| 修订号 | 标识向下兼容的缺陷修复 | 非负整数 | 只修缺陷、改文档、调性能，不改变对外契约 | 2.3.4 |
| 预发布标识 | 标识尚未正式发布的候选版本 | 连字符后接字母数字与点，如 alpha、beta、rc 加序号 | 进入测试、灰度、候选阶段时追加，正式发布时去掉 | 2.4.0-rc.1 |
| 构建元数据 | 标识同一版本号下的具体构建产物 | 加号后接构建号或提交短哈希 | 每次构建生成，不参与版本先后比较 | 2.3.4+build.20240611 |
递增与归零规则
递增规则要写成无歧义的判断顺序，避免同一变更被两个人判成不同位数。可以按以下顺序执行：
- 存在不兼容变更时，主版本号加一，次版本号与修订号归零。
- 无兼容性破坏但新增功能时，次版本号加一，修订号归零。
- 仅修复缺陷时，修订号加一。
- 预发布标识在进入候选阶段时追加，正式发布时移除；同一候选版本的多次构建只更新构建元数据，不改动前三段数字。
需要提前约定一个边界：多个变更合并进同一发布批次时，按批次内最高级别的变更决定进位，例如同批次既有不兼容调整又有缺陷修复，只进主版本号，不重复进位。
版本号与发布批次、制品标识的对应
版本号描述的是对外可见的版本身份，发布批次描述的是团队内部的一次交付活动，制品标识描述的是某个具体的构建产物。三者需要建立明确映射：一个发布批次通常对应一个版本号，一个版本号可以对应多个构建产物，构建元数据承担区分职责。规范中应写明“版本号在批次冻结时确定，制品标识在每次构建时生成”，防止用构建号冒充版本号，或同一版本号对应两份内容不同的制品。
从字段到规则：编写规范的四个步骤
字段表解决“写什么”，四个步骤解决“怎么写出来、怎么验证”。每一步都应有明确的输入、动作、输出和完成标志，避免规范停留在原则层面。
第一步：盘点现有版本号写法
输入是近一年的发布记录、制品库中的版本标签和发布说明。动作是逐条收集实际使用过的版本号，标注位数、分隔符、是否带预发布标识、是否存在同号不同内容的情况。输出是一张现状清单，列出冲突与歧义，例如“1.2”与“1.2.0”混用、日期式版本号与数字式版本号并存、同一版本号对应两次构建。完成标志是清单覆盖全部在维护的版本线，且每条歧义都有具体例子。
第二步：确定结构并写出正反示例
输入是现状清单和团队的兼容性判断标准。动作是确定字段与递增规则，并为每条规则配一个正确写法和一个错误写法。输出是规范草案中的结构章节与示例章节。完成标志是任意一位研发人员能依据示例判断“这次变更该进哪一位”，且示例覆盖不兼容变更、功能新增、缺陷修复、预发布四类场景。
第三步：定义分配时点与冻结时点
输入是团队的发布节奏与分支策略。动作是明确版本号在哪个节点被提出、在哪个节点被冻结、冻结后还能否修改。常见做法是提测时申请候选版本号，发布评审通过后冻结，冻结后只允许更新构建元数据。输出是时点定义与对应的审批动作。完成标志是每个时点都能对应到一个可查记录，而不是口头约定。
第四步：小范围试行并回放历史版本
输入是规范草案和现状清单中的历史版本。动作是选一条在维护的版本线试行一个发布周期，同时用新规则回放历史版本，检查能否复现原有编号或解释差异。输出是试行问题清单与规则修订记录。完成标志是回放中每个历史版本都能被规则解释，无法解释的差异已明确归因为规则缺口或历史遗留，并写入规范附录。
谁在什么时候分配版本号：角色与交付物
版本号由个人临时决定，是规范失效最常见的原因。把分配、审核、冻结、发布四个环节的角色和交接物写清楚，版本号才能成为团队共同维护的交付标识。
| 角色 | 职责边界 | 关键节点 | 交接物 |
|---|---|---|---|
| 版本管理员 | 维护版本号台账，受理版本号申请，检查是否符合规则 | 申请受理、台账更新 | 版本号申请单、版本号台账 |
| 研发负责人 | 判断变更性质，确认进位级别 | 提测前、发布评审 | 变更性质说明、进位判断结论 |
| 测试负责人 | 确认候选版本的测试范围与结论 | 候选版本冻结前 | 测试报告、遗留缺陷清单 |
| 发布负责人 | 执行冻结与发布，核对版本号与发布记录一致 | 冻结、正式发布 | 发布记录、发布说明 |
版本号变更或作废时，规范应要求保留原编号并标注作废原因，禁止回收复用已发布的版本号，避免下游引用指向错误内容。版本号与发布说明、变更记录需要一一关联：发布说明中写明版本号、变更类型和对应需求或缺陷编号，变更记录中回填最终发布的版本号，形成双向可查。
当团队使用研发管理平台承载这一流程时，可以把版本号作为发布记录的固定字段，与需求、缺陷、构建产物关联在同一处。ONES 支持在发布管理与工作项中记录版本信息并关联相关需求与缺陷，使版本号申请、审核结论和发布记录留在同一条可追溯的链路上；具体字段配置与流程设置需按团队实际管理方式进行。
示例：一套可用的版本命名规范
以下条文可直接作为规范文档的骨架，团队按自身情况替换取值与角色名称即可。
规范条文示例
- 版本号格式为“主版本号.次版本号.修订号”，可选追加“-预发布标识”和“+构建元数据”。
- 主版本号在出现不兼容变更时加一，次版本号与修订号归零。
- 次版本号在新增向下兼容功能时加一，修订号归零。
- 修订号在仅修复缺陷时加一。
- 预发布标识使用 alpha、beta、rc 加序号，正式发布时移除。
- 构建元数据在每次构建时生成，不参与版本先后比较。
- 版本号在提测时申请，发布评审通过后冻结，冻结后仅允许更新构建元数据。
三个版本号实例
| 版本号 | 对应变更说明 |
|---|---|
| 3.0.0 | 开放接口鉴权方式调整，旧版 token 不再被接受，属于不兼容变更 |
| 3.1.0 | 新增批量导出接口，原有接口行为不变，属于向下兼容的功能新增 |
| 3.1.1 | 修复导出文件在文件名含特殊字符时截断的缺陷，对外契约不变 |
常见歧义写法与修正
| 歧义写法 | 问题 | 修正后写法 |
|---|---|---|
| v3.1 | 位数不全，无法判断修订号是 0 还是遗漏 | 3.1.0 |
| 3.1.0-final | 用自造后缀表示正式版，排序规则不明确 | 3.1.0 |
| 3.1.0-beta | 缺少序号，多次候选无法区分 | 3.1.0-beta.2 |
| 2024.06.11 | 日期式编号无法表达变更性质 | 3.1.1+build.20240611 |
规范文档建议按“适用范围—字段定义—递增规则—预发布与构建元数据—分配与冻结流程—角色职责—示例—附录（历史版本说明）”组织，把规则条文与操作流程分开写，便于新成员先读规则再查流程。
规范落地后的完成检查
规范写完不等于执行到位。以下检查项用于判断规则是否真正进入日常交付，每项都给出通过标准和证据来源。
| 检查项 | 通过标准 | 证据来源 |
|---|---|---|
| 版本号可机器解析并排序 | 用脚本解析全部在维护版本号，无解析失败；按规则排序结果与发布时间顺序一致 | 解析脚本输出、版本号台账 |
| 历史版本回放符合规则 | 抽样历史版本均能被规则解释，差异已归因并记录 | 回放记录、规范附录 |
| 发布记录与版本号一一对应 | 每个已发布版本号都能找到唯一发布记录，每条发布记录都有版本号 | 发布记录、制品库标签 |
| 新成员可独立编写 | 新成员仅凭规范，对给定变更场景编出正确版本号，无需口头补充 | 编写测试结果、规范文档 |
| 违规可纠正与回溯 | 发现错误版本号时有登记、更正和影响范围排查记录，已发布编号不被复用 | 违规登记表、更正记录 |
检查频率可以跟随发布节奏，每个发布批次结束后抽查一次，季度做一次全量回放。发现违规时，先确认影响范围，包括下游引用、制品标签和发布说明，再按规范登记更正，并把触发违规的规则缺口补进条文，让检查结果反过来完善规范本身。
常见问题
团队已有日期式版本号，是否必须全部改成三段数字结构？
不必一次性全部替换。可以在规范中约定：新发布批次统一使用三段结构，仍在维护的旧版本线保留原编号，在规范附录中登记历史编号与对应关系。日期式编号可以作为构建元数据保留，例如写成 3.1.1+build.20240611，让日期信息继续可查，同时让版本号本身表达变更性质。切换期间需在发布说明中同时标注新旧编号，避免下游引用混乱。
预发布版本多次构建，版本号要不要每次都变？
前三段数字保持不变，只更新构建元数据。预发布标识用于区分候选阶段，例如 2.4.0-rc.1 与 2.4.0-rc.2 表示两轮候选；同一候选版本内的多次构建用加号后的构建号或提交短哈希区分，不参与版本先后比较。正式发布时去掉预发布标识，版本号回到 2.4.0。规范中应写明这一条，防止用构建号冒充版本号。
发布后发现版本号编错了，能不能直接改号重新发布？
已发布的版本号不建议回收或改写。规范应要求保留原编号并标注作废原因，更正后的内容使用新的修订号发布，同时在发布记录中写明两者的对应关系。这样下游引用、制品标签和发布说明都能追溯。若错误只影响内部记录、尚未对外发布，可以在冻结前按流程更正，但需在版本号台账中留下变更记录。
小团队没有专职版本管理员，角色怎么安排？
可以合并角色，但职责要分开写清楚。例如由发布负责人兼任版本管理员，负责台账与规则检查；研发负责人判断变更性质；测试负责人确认候选版本结论。关键是分配与审核不由同一人独自完成，且每个环节留下可查记录。团队规模扩大后再拆分角色，规范条文不需要重写，只调整角色对照表即可。
规范试行一个发布周期后，发现规则覆盖不了某些变更，怎么处理？
把无法解释的案例记入试行问题清单，判断属于规则缺口还是历史遗留。规则缺口补进条文并更新示例；历史遗留写入规范附录，注明原编号与差异原因。补充规则时同步检查递增判断顺序是否仍然无歧义，避免新条文与原有进位规则冲突。修订后的规范需重新做一次历史版本回放，确认原有版本仍能被解释。
