# RT-Thread 版本编号制定与实施细则 [English](release_versioning_en.md) | [版本发布流程](release_process_cn.md) | 项目 | 内容 | | --- | --- | | 版本 | 1.0 | | 日期 | 2026-10-27 | | 适用范围 | RT-Thread 主线版本规划、版本发布和稳定分支维护 | | 配套文档 | [版本发布流程](release_process_cn.md) | 版本节奏:`Z` 版本原则上每 1 个月发布一个;`Y` 版本根据功能积累和维护资源,每 3~6 个月发布一个;`X` 版本不按固定周期发布。 ## 1. 版本号格式 正式版本采用: ```text 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. 版本判定优先级 同一版本包含多类变更时,按最高影响级别确定版本号: ```text 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 个月为周期,由核心维护者评审后决定是否发布 | **发布策略:** 1. CI 提供测试清单及对应测试用例固件。 2. 测试人员执行人工验证,并上传测试结果。 3. AI 通过提示词或 SKILL 汇总生成版本测试报告。 4. 人工审核报告,核心维护者结合功能积累和验证结果决定是否发布。 ### 4.3 `Z` 版本 **前提:主线建立一套初步完备的自动化运行机制。** | 项目 | 实施要求 | | --- | --- | | 维护方式 | 以 QEMU + CI 自动化为主 | | 测试范围 | 内核、组件及仿真支持范围内的驱动 | | 核心目的 | 定期收敛主线,小步发布,方便后续追溯 | | 发布频次 | 以一个月为周期评估,由人工决定是否触发发布 | **发布策略:** 1. CI 自动执行测试,统计测试覆盖率和测试通过率。 2. CI 生成版本测试报告,包含覆盖率、通过率、本次版本新增提交的功能说明及已知问题。 3. 自动创建版本发布提议 Discussion,通知核心维护者参与讨论。 4. 核心维护者决定是否发布;短期新增修复或优化提交较少时,可跳过本次发布。 总体通过率不要求达到 100%,但必须列出已知问题,供维护者评估后作出发布决定。 ## 5. 版本制定流程 具体发布阶段与工作分工参见[版本发布流程](release_process_cn.md)。 ```text 需求或 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 一致。