Files

9.9 KiB
Raw Permalink Blame History

RT-Thread 版本编号制定与实施细则

English | 版本发布流程

项目 内容
版本 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 个月为周期,由核心维护者评审后决定是否发布

发布策略:

  1. CI 提供测试清单及对应测试用例固件。
  2. 测试人员执行人工验证,并上传测试结果。
  3. AI 通过提示词或 SKILL 汇总生成版本测试报告。
  4. 人工审核报告,核心维护者结合功能积累和验证结果决定是否发布。

4.3 Z 版本

前提:主线建立一套初步完备的自动化运行机制。

项目 实施要求
维护方式 以 QEMU + CI 自动化为主
测试范围 内核、组件及仿真支持范围内的驱动
核心目的 定期收敛主线,小步发布,方便后续追溯
发布频次 以一个月为周期评估,由人工决定是否触发发布

发布策略:

  1. CI 自动执行测试,统计测试覆盖率和测试通过率。
  2. CI 生成版本测试报告,包含覆盖率、通过率、本次版本新增提交的功能说明及已知问题。
  3. 自动创建版本发布提议 Discussion,通知核心维护者参与讨论。
  4. 核心维护者决定是否发布;短期新增修复或优化提交较少时,可跳过本次发布。

总体通过率不要求达到 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 一致。