第2章 版本号命名规范：语义化版本规则、主版本/次版本/补丁/构建号定义、预发布后缀
适用场景：
- 适用于所有需要对外发布或内部迭代的OTA固件包；
- 区分开发（Dev）、测试（Test）、生产（Production）环境的固件版本；
- 自动化CI/CD流水线中的版本管理，确保每次构建结果可追溯、可回退。
前置条件：
- 产品线架构团队已确立主版本/次版本的基线策略与发布节奏；
- 已确定构建号（Build Number）的递增规则（如基于CI流水线唯一ID或Git提交深度）；
- 开发及测试团队成员已对齐语义化版本的基本概念及版本变更标记规范。
操作流程
- 确定基础版本号格式： 严格遵循
MAJOR.MINOR.PATCH三段式语义化版本规则。- 主版本（MAJOR）： 进行不向下兼容的API/协议变更、重大产品架构重构时递增。
- 次版本（MINOR）： 新增向下兼容的功能、特性或协议扩展时递增。
- 补丁（PATCH）： 进行向下兼容的缺陷修复、安全补丁或性能优化时递增。
- 附加构建号（Build Number）： 格式演进为
MAJOR.MINOR.PATCH.BUILD。- 构建号由CI系统（如Jenkins、GitLab CI、GitHub Actions）每次成功构建时自动生成，作为单次构建的唯一标识。
- 推荐使用CI流水线的运行时唯一ID（Pipeline IID）或完整的Git提交哈希作为构建号来源，确保可精确追溯。
- 标记预发布后缀： 格式为
MAJOR.MINOR.PATCH-PRE_RELEASE_TYPE.PRE_RELEASE_VERSION。- alpha： 内部开发版，用于开发人员自测及交叉验证，功能可能不完整或不稳定。
- beta： 公开测试版，面向小范围用户或测试团队，功能基本冻结，用于收集反馈。
- rc（Release Candidate）： 候选正式版，与正式版仅有一步之遥，通过最终验证后直接转为正式版。
- 预发布版本的排序优先级低于对应的正式发布版本，且永远遵循
alpha < beta < rc的成熟度顺序。
- 生成完整版本字符串：
- 正式发布：
MAJOR.MINOR.PATCH.BUILD（例如：3.2.1.5678）。 - 预发布：
MAJOR.MINOR.PATCH-PRE_TYPE.PRE_VER+BUILD_META（例如：3.2.1-beta.1.5678或3.2.1-rc.1+20231027）。
- 正式发布：
- 验证版本号唯一性： 将生成的完整版本字符串与制品仓库（Artifact Repository）中已归档的历史版本进行机械比对，严禁出现版本号重复覆盖的情况。
输入输出物
| 类型 | 名称 | 来源 / 格式 | 说明 |
|---|---|---|---|
| 输入 | 版本变更类型 | Git Commit Message / MR标签 (fix/feat/breaking) | 语义化版本自动推导的原始依据 |
| 输入 | 构建环境元数据 | CI环境变量 / Git 原生数据 | 流水线唯一ID、Git提交SHA、时间戳 |
| 输入 | 发布阶段标识 | CI手动触发参数 / 分支命名策略 (main/release/develop) | 区分开发版、测试版、候选版、正式版 |
| 输出 | 唯一版本号字符串 | VERSION 文件 / 固件编译宏定义 | 遵循 MAJOR.MINOR.PATCH.BUILD[-PRE_RELEASE] 规范 |
| 输出 | 版本归档记录 | 制品仓库日志 / CHANGELOG.md | 确保每个版本号精确对应一个不可变制品 |
责任边界
| 角色 | 职责 | 触发的关键动作 |
|---|---|---|
| 版本经理（Release Manager） | 定义版本命名基线策略，审批主版本/次版本升级，确认发布阶段标识 | 创建发布分支、打Git Tag、触发正式版CI流水线 |
| 开发人员 | 遵循 [约定式提交](https://www.conventionalcommits.org/) 规范标记变更类型 | 提交代码时正确使用 fix: / feat: / BREAKING CHANGE: 前缀 |
| CI/CD 系统管理员 | 配置CI流水线自动化解析版本、注入构建号、执行唯一性校验 | 编写版本生成脚本（如 ci/gen_version.sh），配置版本校验网关 |
| 测试人员 | 根据预发布后缀（alpha/beta/rc）理解固件成熟度，制定准入测试标准 | 在测试用例中声明适用的版本范围，拦截不合规的版本推送 |
记录材料
- VERSION 文件： 存放于代码库根目录，记录当前开发基线的主版本/次版本/补丁版本。
- CHANGELOG.md 文件： 人工或自动生成的版本变更日志，每个版本条目必须与语义化版本一一对应。
- CI 构建日志： 完整记录编译时间、版本号推导过程、构建号来源及制品存储路径。
- 制品仓库归档列表： 按产品线/版本号组织的固件包存储记录（如S3桶、Nexus仓库）。
异常处理：
- 情况1：MAJOR/MINOR/PATCH 递增决策错误。
- 影响： 版本语义混乱，导致下游 OTA 升级网关误判兼容性。
- 处理方案： 在 CI 代码审查（Code Review）阶段新增「版本变更标签」审核机器人，强制拦截不合规的版本号提升操作。
- 情况2：构建号冲突或未正确生成。
- 影响： 两个物理上不同的固件包拥有相同版本标识，导致设备升级回退时出现不可预期的状态翻转。
- 处理方案： CI 系统配置全局唯一的构建计数器，并在制品上传时进行原子性校验；若发现制品仓库已存在同名版本号，立即中断构建并告警。
- 情况3：预发布后缀拼写错误。
- 影响： OTA 服务器版本解析过滤器（Filter）无法识别自定义后缀，导致版本被归类到错误的分发渠道。
- 处理方案： 在 VERSION 文件和 CI 脚本中设置预发布后缀枚举白名单（如
alpha|beta|rc|release），超出白名单范围的构建直接标记为失败。
- 情况4：版本号超长导致固件溢出。
- 影响： 固件版本号存储缓冲区溢出，引发内存损坏或版本对比逻辑异常。
- 处理方案： 在编译阶段使用
_Static_assert约束版本号字符串长度；在 CI 脚本中限制构建号的最大数值（例如：MAX_BUILD=65535）。
验收标准
- 发布的固件版本号严格遵循
MAJOR.MINOR.PATCH.BUILD[-PRE_RELEASE]模式。 - 通过OTA服务器日志可精确将版本号溯源至CI构建记录和Git提交哈希。
- CHANGELOG.md 中记录的变更类型与版本号的语义化提升方向完全一致。
- 预发布版本（以
alpha/beta/rc结尾）不会被误推送至正式发布（Production）渠道。 - 制品仓库中所有版本号均全局唯一，不存在任何覆盖或冲突记录。