4. ST Stellar软件版本命名与编号规范

在ST Stellar这类面向量产的车规级MCU软件项目中，版本号不是给开发者自己看的备注，而是贯穿需求、开发、测试、发布、OTA升级、产线烧录和售后追溯的“身份证”。一个规范的版本命名体系，必须同时回答四个问题：这个版本从哪个基线演化而来、它包含哪些功能变更、它是否经过完整验证、它能不能被安全地刷写到量产件上。本节围绕语义化版本、内部版本、发布版本、补丁版本与量产标识五个层次，说明如何设计一套可机器解析、可人工识别、可长期维护的编号规范。

一、语义化版本：对外承诺的兼容性契约

语义化版本（Semantic Versioning）采用 MAJOR.MINOR.PATCH 三段式结构，其核心约定是：主版本号变更表示存在不兼容的接口或行为变化；次版本号变更表示以向后兼容的方式新增功能；修订号变更表示向后兼容的问题修复。对Stellar软件而言，这里的“接口”不仅指C API，还包括寄存器映射、外设驱动行为、诊断服务（UDS）响应、标定参数地址布局以及Bootloader与Application之间的跳转约定。

例如，某Stellar项目当前对外版本为 2.4.1。若新增一路CAN FD通道的发送API且不破坏既有调用，应发布 2.5.0；若仅修复ADC采样在低温下偶发丢帧的问题，应发布 2.4.2；若修改了Flash分区表导致旧版Bootloader无法识别新Application，则必须发布 3.0.0。这里的关键判断依据是“兼容性是否被破坏”，而不是“代码改动量大小”。

二、内部版本：开发过程中的可追溯锚点

语义化版本只描述对外兼容性，无法区分同一对外版本下的大量中间构建。因此需要内部版本号，通常由构建系统自动生成，格式建议为 MAJOR.MINOR.PATCH+BUILD 或 MAJOR.MINOR.PATCH-rc.N。其中 BUILD 建议直接使用Git提交短哈希与流水线序号组合，例如 2.5.0+git.a3f9c21.1847，表示第1847次CI构建、对应提交a3f9c21。

内部版本必须满足两个条件：一是全局唯一，任何两次构建不得产生相同编号；二是可反查，通过编号能定位到确切的源码提交、工具链版本和构建参数。在Stellar项目中，建议将内部版本写入芯片的OTP或Flash固定信息区，并在启动日志中打印，便于现场问题复现。

三、发布版本与补丁版本：从候选到定版

发布版本是在内部版本基础上，经过完整验证并冻结的版本。推荐使用 MAJOR.MINOR.PATCH 加发布标识，如 2.5.0-release。在正式发布前，应经过 alpha、beta、rc 三个阶段：2.5.0-alpha.1 用于功能自测，2.5.0-beta.2 用于系统集成，2.5.0-rc.1 用于量产前最终验证。只有 rc 通过全部准出测试后，才允许去掉后缀成为正式发布版本。

补丁版本用于已发布版本的紧急修复，必须保持 MAJOR.MINOR 不变，仅递增 PATCH，例如从 2.5.0 修复为 2.5.1。补丁版本不允许引入新功能，不允许改变接口，只允许修复缺陷或安全问题。若修复必须改变接口，则应升级次版本号而非补丁号。

四、量产标识：区分“能跑”与“能装车”

量产标识是版本体系中最后也是最关键的一层。它不描述功能，而描述“这个版本被允许用于哪种生产状态”。建议采用独立字段，如 MP（Mass Production）、PP（Pre-Production）、ENG（Engineering）。完整版本字符串可设计为：

2.5.1-MP+git.a3f9c21.1847
2.5.0-PP+git.b7e2d10.1793
2.6.0-ENG+git.c1a4f88.1902

其中 MP 表示已通过PPAP/量产准出，可用于产线烧录和OTA推送；PP 表示小批量试产验证，允许在受控范围内装车；ENG 仅用于工程调试，禁止流入量产环节。产线烧录工具应校验该字段，遇到非 MP 版本时拒绝烧录或强制告警。

五、版本号生成与校验的工程实现

规范要落地，必须由工具链强制执行。推荐在CI流水线中通过脚本自动生成版本号，并在编译阶段写入固件。以下是一个简化的版本头文件生成示例：

# 由CI脚本根据Git标签和构建环境生成 version.h
#define FW_VERSION_MAJOR   2
#define FW_VERSION_MINOR   5
#define FW_VERSION_PATCH   1
#define FW_VERSION_STAGE   "MP"
#define FW_VERSION_BUILD   "git.a3f9c21.1847"
#define FW_VERSION_STRING  "2.5.1-MP+git.a3f9c21.1847"

在产线烧录环节，烧录工具应读取固件中的 FW_VERSION_STAGE 字段，并与工单要求的版本进行比对。若工单要求 MP 而固件为 ENG，工具应直接拒绝并记录审计日志。在OTA场景中，车端应校验新版本的主版本号是否与当前硬件平台兼容，避免跨大版本误刷导致变砖。

六、常见错误与规避建议

• 用日期代替语义化版本：如 20240612，无法表达兼容性，应改为 2.5.1 并在内部版本中保留日期信息。
• 内部版本重复：同一提交多次构建产生相同编号，导致无法区分测试对象。应强制加入流水线序号。
• 补丁版本夹带新功能：破坏“补丁仅修复”的约定，导致下游无法判断升级风险。应严格代码评审和变更分类。
• 量产标识缺失或手工填写：容易误将工程版本流入产线。应由CI根据分支和标签自动判定，禁止人工覆盖。

一套好的版本规范，最终要能让测试工程师看一眼版本号就知道该测什么、让产线工人扫一下就知道能不能烧、让售后工程师查一下就知道装的是哪版软件。语义化版本管兼容，内部版本管追溯，发布版本管冻结，补丁版本管修复，量产标识管准入——五层各司其职，才能支撑Stellar软件从开发到量产的完整治理闭环。