【嵌入式】嵌入式系统中的 SemVer 版本控制方案

嵌入式系统中的 SemVer 版本控制方案

在嵌入式系统开发中，采用 语义化版本控制（SemVer, Semantic Versioning） 能帮助团队清晰地管理 固件（Firmware）、驱动（Driver） 和 软件（Software） 版本，确保兼容性和稳定性。

1. SemVer 版本号格式

标准的 SemVer 2.0.0 规则如下：

MAJOR.MINOR.PATCH

其中：

• MAJOR（主版本号）：不兼容的 API 变更（重大架构调整、硬件不兼容）
• MINOR（次版本号）：向后兼容的新功能（增加新特性、优化性能）
• PATCH（补丁版本号）：向后兼容的 Bug 修复（修复错误、不影响接口）

🔹 示例

2. 嵌入式中的扩展规则

2.1 额外的构建号（Build Metadata）

嵌入式项目中，除了 MAJOR.MINOR.PATCH，可能还需要额外信息，比如：

MAJOR.MINOR.PATCH.BUILD

BUILD（构建号）：内部编译版本，用于区分同一个版本的不同构建

在 CI/CD 自动化构建时加上 Git 提交 ID 或时间戳，如：

1.2.3+20240314
1.2.3+commitabc123

用于调试、回溯固件版本，不影响 SemVer 兼容性

🔹 示例

2.2 预发布版本（Pre-release）

嵌入式开发中可能有 Alpha/Beta 版本，可使用 SemVer 预发布标签：

MAJOR.MINOR.PATCH-PRERELEASE

• Alpha（-alpha）：早期测试版，可能有大量 Bug
• Beta（-beta）：稳定性提高，但仍在测试
• RC（-rc）：接近最终发布的候选版本

🔹 示例

2.3 特殊版本（修订号）

一些嵌入式项目可能会额外加 修订号（REVISION），用于区分硬件兼容性：

MAJOR.MINOR.PATCH.REVISION

用于不同的硬件版本（PCB 版本） 例如：

1.2.3.001  # 适用于 PCB v1.0
1.2.3.002  # 适用于 PCB v1.1

用于 Bootloader 和固件的匹配

Bootloader: 1.0.0
Firmware:   1.2.3.001

3. 在 Git / CI/CD 中应用 SemVer

3.1 Git 标签（Git Tag）

Git 版本管理中，一般使用 git tag 进行版本标记：

git tag v1.2.3
git push origin v1.2.3

或带 预发布标签：

git tag v1.2.3-beta.1
git push origin v1.2.3-beta.1

3.2 GitHub Actions / GitLab CI 结合 SemVer

在 CI/CD 自动化构建时，可自动生成版本：

获取最新 Tag

git describe --tags --always

基于 git rev-list 计算 BUILD 号

BUILD_NUM=$(git rev-list --count HEAD)
echo "1.2.3+$BUILD_NUM"

示例：

Firmware Version: 1.2.3+4578

3.3 在固件中嵌入版本号

嵌入式系统可在代码中定义版本号，方便调试：

#define FIRMWARE_VERSION "1.2.3"
#define BUILD_NUMBER     "4567"

printf("Firmware: %s (Build %s)\n", FIRMWARE_VERSION, BUILD_NUMBER);

4. C 语言项目中的 SemVer 规则

C 语言项目需要管理 库版本、头文件，常用方式如下：

4.1 头文件中定义版本号

在 version.h 头文件中定义：

#ifndef VERSION_H
#define VERSION_H

#define PROJECT_NAME "MyEmbeddedApp"
#define VERSION_MAJOR 1
#define VERSION_MINOR 2
#define VERSION_PATCH 3
#define VERSION_STRING "1.2.3"

#endif // VERSION_H

然后在 main.c 中使用：

#include <stdio.h>
#include "version.h"

int main() {
    printf("Project: %s\n", PROJECT_NAME);
    printf("Version: %d.%d.%d\n", VERSION_MAJOR, VERSION_MINOR, VERSION_PATCH);
    return 0;
}

💡 作用：程序运行时可以打印版本信息，方便排查问题。

4.2 预发布和构建版本

SemVer 允许：

• 预发布版本：1.2.3-alpha.1
• 自动构建号：1.2.3+4567

在 version.h 里增加：

#define VERSION_PRERELEASE "alpha.1"
#define BUILD_NUMBER "4578"

然后在 main.c 里：

#ifdef VERSION_PRERELEASE
    printf("Pre-release: %s\n", VERSION_PRERELEASE);
#endif
#ifdef BUILD_NUMBER
    printf("Build: %s\n", BUILD_NUMBER);
#endif

💡 作用：区分开发版和正式版。

5. SemVer 在嵌入式项目中的实际应用

6. 总结

✅ 标准 SemVer： MAJOR.MINOR.PATCH ✅ 嵌入式扩展： MAJOR.MINOR.PATCH.BUILD（构建号） ✅ 预发布版本： MAJOR.MINOR.PATCH-PRERELEASE（Alpha/Beta/RC） ✅ 硬件兼容版本： MAJOR.MINOR.PATCH.REVISION（区分 PCB 版本） ✅ Git / CI/CD 支持： git tag v1.2.3 + git describe

🔹 推荐做法：

1. 正式版本：1.2.3
2. 开发测试：1.2.3-beta.1
3. 自动构建：1.2.3+4567
4. 不同硬件兼容：1.2.3.001

💡 采用 SemVer 让嵌入式项目的版本管理更加清晰，提高开发效率！🚀