9.9 KiB
RT-Thread 版本编号制定与实施细则
| 项目 | 内容 |
|---|---|
| 版本 | 1.0 |
| 日期 | 2026-10-27 |
| 适用范围 | RT-Thread 主线版本规划、版本发布和稳定分支维护 |
| 配套文档 | 版本发布流程 |
版本节奏:Z 版本原则上每 1 个月发布一个;Y 版本根据功能积累和维护资源,每 3~6 个月发布一个;X 版本不按固定周期发布。
1. 版本号格式
正式版本采用:
vX.Y.Z
示例:v6.0.0、v6.1.0、v6.1.1。
版本号与源码版本宏、Git Tag、Release 和交付物名称必须一致:
| 项目 | 示例 |
|---|---|
| Git Tag | v6.1.0 |
RT_VERSION_MAJOR |
6 |
RT_VERSION_MINOR |
1 |
RT_VERSION_PATCH |
0 |
日常提交不增加正式版本号。开发快照使用目标版本、完整 Git SHA 和构建记录标识,不得标记为已发布正式版本。
2. 版本段定义
| 版本段 | 升级定位 | RT-Thread 典型场景 |
|---|---|---|
X 主版本 |
重大特性更新或整体技术体系升级 | 全新内核、内核核心机制重构、全新设备或驱动框架、系统架构级调整、多个核心子系统协同升级、需要用户迁移的重大 API/ABI 或配置体系变化 |
Y 次版本 |
现有内核和框架上的功能扩展;根据功能积累和资源情况每 3~6 个月发布 | 新增内核或组件 API、驱动框架能力、文件系统或网络能力、架构或芯片系列支持,以及形成完整交付能力的一组 BSP 或组件功能 |
Z 修订版本 |
小范围修复、支持和局部完善;原则上每 1 个月发布 | BUG 修复、安全修复、局部功能完善、性能/资源优化、单个 BSP 适配、构建修复和文档修复 |
2.1 X 主版本
升级 X 需综合提审决定:
- 引入全新内核或替换内核核心机制;
- 引入全新设备模型、驱动框架或系统级软件框架;
- 多个核心子系统协同升级,改变系统整体使用方式;
- 删除、重命名或改变公共 API、ABI、结构体布局、系统调用约定;
- 改变 Kconfig、配置格式、启动流程或数据格式,导致已有工程需要迁移;
- 虽保持部分 API 兼容,但整体能力和架构已构成一次主要升级。
配套功能统一纳入同一主版本规划。
2.2 Y 次版本
满足以下条件时,升级 Y:
- 新增内核 API、组件 API 或可复用的公共能力,并保持已有接口兼容;
- 新增驱动框架、文件系统、网络协议栈或软件包框架能力;
- 新增架构、芯片系列或一组 BSP 支持,形成可独立交付的平台能力;
- 多个相关小功能达到版本目标,形成完整、可验证、可发布的功能集合。
单个零散功能、局部参数扩展或单一实现优化不自动触发 Y。功能必须达到版本 Milestone 规定的交付范围,并具备对应测试证据。Y 版本周期为 3~6 个月,具体周期一旦确定,需在版本目标中明确;无法在周期内完成验证的功能顺延至下一版本。
2.3 Z 修订版本
满足以下条件时,升级 Z:
- 修复死锁、越界、内存泄漏、启动失败、安全漏洞、构建失败或性能回归;
- 完善局部功能、错误处理、日志、性能或资源使用;
- 增加单个 BSP、单个芯片或单个平台适配;
- 修复文档、测试、构建脚本或发布材料。
Z 版本不得引入新的公共 API、完整组件、驱动框架、架构体系或计划性不兼容变化。单个 BSP 若引入新的驱动框架、设备模型或公共 API,应升级为 Y 或 X。
3. 版本判定优先级
同一版本包含多类变更时,按最高影响级别确定版本号:
X 主版本 > Y 次版本 > Z 修订版本
| 组合情况 | 版本判定 |
|---|---|
| 重大内核/框架变更 + 组件新增 + BUG 修复 | X |
| 组件/API/平台能力新增 + 局部修复 | Y |
| BUG 修复 + 单个 BSP 适配 + 性能优化 | Z |
| 仅文档、测试、CI 或发布材料变更 | 不升级正式版本 |
不按提交数量、PR 数量、代码行数或开发周期长度决定版本号,以功能边界、用户影响、架构影响和交付完整度为准。
4. 版本段实施细则
发布依据:周期性 + 功能特性累计。
推荐开发者使用 X/Y 版本;Z 版本仅作为阶段性版本收敛节点,方便追溯。
4.1 X 版本
待讨论。
4.2 Y 版本
| 项目 | 实施要求 |
|---|---|
| 维护方式 | 人力 + CI,侧重 BSP 和驱动维护的人力投入 |
| 核心目的 | 围绕重大驱动框架、内核 API 变更、全新架构及框架支持,进行版本收敛发布 |
| 发布频次 | 以 3~6 个月为周期,由核心维护者评审后决定是否发布 |
发布策略:
- CI 提供测试清单及对应测试用例固件。
- 测试人员执行人工验证,并上传测试结果。
- AI 通过提示词或 SKILL 汇总生成版本测试报告。
- 人工审核报告,核心维护者结合功能积累和验证结果决定是否发布。
4.3 Z 版本
前提:主线建立一套初步完备的自动化运行机制。
| 项目 | 实施要求 |
|---|---|
| 维护方式 | 以 QEMU + CI 自动化为主 |
| 测试范围 | 内核、组件及仿真支持范围内的驱动 |
| 核心目的 | 定期收敛主线,小步发布,方便后续追溯 |
| 发布频次 | 以一个月为周期评估,由人工决定是否触发发布 |
发布策略:
- CI 自动执行测试,统计测试覆盖率和测试通过率。
- CI 生成版本测试报告,包含覆盖率、通过率、本次版本新增提交的功能说明及已知问题。
- 自动创建版本发布提议 Discussion,通知核心维护者参与讨论。
- 核心维护者决定是否发布;短期新增修复或优化提交较少时,可跳过本次发布。
总体通过率不要求达到 100%,但必须列出已知问题,供维护者评估后作出发布决定。
5. 版本制定流程
具体发布阶段与工作分工参见版本发布流程。
需求或 PR 提出版本建议
-> 模块维护者初判
-> 核心维护小组复核高风险变更
-> 纳入版本 Milestone
-> 功能冻结前确认 X.Y
-> 发布前确认 X.Y.Z
-> 发布负责人创建 Tag 和 Release
5.1 版本准备阶段
- 整理上一版本遗留问题、社区需求和新增功能。
- 按功能影响初步标记
X、Y或Z。 - 创建版本 Milestone,明确必达、可延期和不纳入范围。
- 指定版本负责人、模块维护者、目标平台和测试责任人。
Z版本按 1 个月周期倒排;Y版本根据功能规模和资源情况确定 3~6 个月的周期,先确认测试能力和维护人员,再确定功能范围。
5.2 版本开发阶段
- 新功能合入 PR 时填写建议版本级别和判定理由。
- 模块维护者确认功能边界、兼容性和测试范围。
- 发现
X级变更时,必须重新评估版本目标、迁移成本和发布时间。 - 发现新增功能无法形成完整交付时,留在主线,顺延至下一版本;不通过修改版本号掩盖范围变化。
- 一个发布周期只维护一个
Y版本目标,不为满足发布日期临时接收未经测试的大型功能;未完成验证的功能顺延至下一版本。
5.3 功能冻结阶段
Z版本发布前约一个月进入修复收敛;Y版本发布前约一个月进入功能收敛,冻结前确定本次发布的X.Y。- 冻结后不得新增功能、公共 API、组件或框架能力。
- 冻结后只允许修复发布阻断问题、必要的安全问题和发布材料。
- 冻结后发生
X或Y级变化,移出当前版本,分别重新规划重大版本或下一期 3~6 个月周期的次版本。
5.4 正式发布阶段
- 发布版本确定为
X.Y.0,或在稳定分支上确定为X.Y.Z。 - 发布负责人检查版本宏、Git Tag、Release、变更日志和交付物是否一致。
- 正式发布后发现问题,发布新的
X.Y.Z+1,不得修改原 Tag、原 Release 内容或原交付物。
5.5 发布节奏
| 周期 | 主要工作 |
|---|---|
| 1 个月 | 发布 Z 版本,集中处理缺陷、安全问题、局部优化和 BSP 适配 |
| 3~6 个月 | 当功能集合、测试范围和维护资源达到要求时,发布一个 Y 版本 |
X 版本 |
根据内核、框架或系统级升级准备情况单独立项,不受固定周期约束 |
各类版本均不要求固定发布日期。发布保障范围内存在阻断问题时允许顺延,不得通过减少已承诺测试、降低支持范围或跳过高风险评审强行发布。Y 版本周期一经确定,不因临时增加功能而缩短。
6. 兼容性和迁移要求
以下变化必须进行兼容性评审:
- 线程调度、IPC、定时器、内存管理、中断或 SMP 的公开接口和行为;
- 设备驱动接口、BSP 初始化流程、Kconfig、默认配置和组件配置格式;
- 文件系统、网络协议栈、软件包 API、错误码、阻塞语义和中断上下文限制;
- 结构体布局、ABI、工具链要求、默认栈大小、堆布局和关键资源占用。
兼容性变化必须登记受影响对象、迁移方式、代表性 BSP 和已知限制。X 版本必须提供迁移说明;Y 和 Z 版本若改变默认行为或资源占用,也必须在 Release 中明确说明。
7. 版本发布检查
- 版本 Milestone 已明确必达范围和版本目标。
- 所有纳入变更完成
X/Y/Z判定。 X级变更已由核心维护小组批准。Y级功能已达到可独立交付状态并完成测试。Z级变更未引入新公共 API、完整组件或框架能力。- 冻结后没有未批准的功能变化。
RT_VERSION_MAJOR/MINOR/PATCH与 Git Tag 一致。