diff --git a/documentation/7.contribution/INDEX.md b/documentation/7.contribution/INDEX.md index d4d5a3ee5bce..67c2f4d00a1a 100644 --- a/documentation/7.contribution/INDEX.md +++ b/documentation/7.contribution/INDEX.md @@ -11,3 +11,8 @@ All the real-time operating system kernel and open source components can be used @subpage page_bsp_contribution_guide_en @subpage page_howto_doxygen + +@subpage page_release_versioning_en + +@subpage page_release_process_en + diff --git a/documentation/7.contribution/figures/release_process_overview_cn.png b/documentation/7.contribution/figures/release_process_overview_cn.png new file mode 100644 index 000000000000..3a0c198498a6 Binary files /dev/null and b/documentation/7.contribution/figures/release_process_overview_cn.png differ diff --git a/documentation/7.contribution/figures/release_process_stage_1_cn.png b/documentation/7.contribution/figures/release_process_stage_1_cn.png new file mode 100644 index 000000000000..2d2fb8541d04 Binary files /dev/null and b/documentation/7.contribution/figures/release_process_stage_1_cn.png differ diff --git a/documentation/7.contribution/figures/release_process_stage_2_cn.png b/documentation/7.contribution/figures/release_process_stage_2_cn.png new file mode 100644 index 000000000000..4ad872eb5016 Binary files /dev/null and b/documentation/7.contribution/figures/release_process_stage_2_cn.png differ diff --git a/documentation/7.contribution/figures/release_process_stage_3_cn.png b/documentation/7.contribution/figures/release_process_stage_3_cn.png new file mode 100644 index 000000000000..4ce76a7480f7 Binary files /dev/null and b/documentation/7.contribution/figures/release_process_stage_3_cn.png differ diff --git a/documentation/7.contribution/figures/release_process_stage_4_cn.png b/documentation/7.contribution/figures/release_process_stage_4_cn.png new file mode 100644 index 000000000000..685e1f8b9057 Binary files /dev/null and b/documentation/7.contribution/figures/release_process_stage_4_cn.png differ diff --git a/documentation/7.contribution/figures/release_process_stage_5_cn.png b/documentation/7.contribution/figures/release_process_stage_5_cn.png new file mode 100644 index 000000000000..8d4fb90614bb Binary files /dev/null and b/documentation/7.contribution/figures/release_process_stage_5_cn.png differ diff --git a/documentation/7.contribution/figures/release_process_stage_6_cn.png b/documentation/7.contribution/figures/release_process_stage_6_cn.png new file mode 100644 index 000000000000..da9f1da7fed6 Binary files /dev/null and b/documentation/7.contribution/figures/release_process_stage_6_cn.png differ diff --git a/documentation/7.contribution/release_process_cn.md b/documentation/7.contribution/release_process_cn.md new file mode 100644 index 000000000000..df3ff6ca1e36 --- /dev/null +++ b/documentation/7.contribution/release_process_cn.md @@ -0,0 +1,120 @@ +# RT-Thread 版本发布流程 + +[English](release_process_en.md) | [版本编号制定与实施细则](release_versioning_cn.md) + +本文描述 RT-Thread 主线版本从需求准备到正式发布的六个阶段。版本号判定、兼容性要求和发布检查参见[版本编号制定与实施细则](release_versioning_cn.md)。 + +## 阶段一:版本准备工作 + +### 1. 首要目标 + +- 确定本版本最终的开发任务,并生成版本开发任务视图。 + +### 2. 主要内容 + +#### 重点内容 + +- 版本草案整理:整理上一个版本的完成度文档,并结合上一版本的版本开发草案,制定本次版本的初步计划。 +- GitHub Issue 整理:整理历史版本遗留问题 Issue,收集版本新特性 Issue,并使用版本 Label 标记。 + +#### 其他内容 + +- 其他部门需求汇总:收集其他部门的功能性需求,整理成需求文档。 +- 前沿技术:评估市面上的新技术,考虑是否移植到主线,以 Issue 或 Discussions 形式记录。 +- 竞品分析:对比同类产品性能差异,分析可引入的特性,以 Issue 或 Discussions 形式记录。 + +![阶段一:版本草案、Issue、部门需求、前沿技术和竞品分析](figures/release_process_stage_1_cn.png) + +## 阶段二:制定下个版本的初步目标 + +### 1. 首要目标 + +- 确定下个版本的初步任务。 + +### 2. 主要内容 + +1. 从上一版本发布后开始收集社区需求反馈,整理成 Issue。 +2. 根据 Issue 汇总成 Milestone。 +3. 制定下一版本的初步目标。 + +![阶段二:从 GitHub Issue 到 Milestone,再制定下一版本初步目标](figures/release_process_stage_2_cn.png) + +## 阶段三:版本开发准备阶段 + +### 1. 首要目标 + +- 根据版本开发任务视图分配开发人员任务。 + +### 2. 主要内容 + +- 为本次版本的开发任务分配开发人员。 +- 指派审查人员对不同特性的 PR 进行审查。 + +![阶段三:开发任务分配和内核、驱动、组件、BSP、CI 等 PR 的审查指派](figures/release_process_stage_3_cn.png) + +## 阶段四:版本开发阶段 + +### 1. 首要目标 + +- 跟踪完成情况,提前通知冻结特性。 + +### 2. 主要内容 + +- 完成版本开发目标,并在版本计划中记录进度。 +- 对核心 PR,在发布前半个月通知冻结特性。 +- 使用 GitHub Label 标记社区开发者提出的新特性 PR。 +- 处理常规 PR,这部分可贯穿版本开发。 + +![阶段四:处理常规 PR、推进核心 PR,并标记社区新特性 PR](figures/release_process_stage_4_cn.png) + +## 阶段五:预发布阶段 + +### 1. 首要目标 + +- 完成特性收敛和 BUG 回归工作。 + +### 2. 主要内容 + +#### 核心工作 + +- 完成特性收敛工作,推动作者完成新特性 PR 的合并。 +- 完成 BUG 回归工作,收集社区反馈的版本问题,包括开发版本及发布版本。 + +#### 测试工作 + +- 结合版本测试用例模板,对不同架构、BSP、内核、组件、外设、文件系统等内容进行测试并记录问题。参考[上一版本的测试用例文档](https://docs.qq.com/sheet/DYUFZbEdrek1KWFd4)。 + +#### 总结工作 + +- 汇总版本开发任务进度和社区开发者新特性 PR,形成版本任务完成度文档。 + +![阶段五:特性收敛、BUG 回归、测试和版本任务完成度总结](figures/release_process_stage_5_cn.png) + +## 阶段六:版本发布 + +### 1. 重点工作 + +- 在 GitHub 发布版本 Tag 及 Release。 +- 在 Gitee 发布版本 Tag 及 Release。 +- 编写版本新特性说明文档。 +- 编写 GitHub Release 版本英文日志,参考[版本对比](https://github.com/RT-Thread/rt-thread/compare/v5.0.1...v5.0.2)。 +- 发布社区公众号版本发布推文。 +- 举办版本发布会。 + +### 2. 其他工作 + +- 在社区发布版本意见征集帖,邀请开发者参与讨论。 +- 更新 RT-Thread Studio 工程文件,发布新版本工程。 +- 更新商业网站的芯片支持情况,主要更新新支持的架构,参考[芯片支持页面](https://www.rt-thread.com/products/Chip-39.html)。 +- 在文档中心更新新支持功能的文档及链接,参考[文档中心](https://www.rt-thread.org/document/site/#/)。 +- 更新官方网站 RT-Thread 源代码网盘下载链接,参考[源代码下载页面](https://www.rt-thread.org/download.html#download-rt-thread-source-code)。 + +![阶段六:发布 Tag 和 Release,更新发布日志、社区公告及相关网站](figures/release_process_stage_6_cn.png) + +## 版本发布流程总视图 + +![RT-Thread 版本发布流程六阶段总视图](figures/release_process_overview_cn.png) + +## 参考资料 + +- [腾讯文档:版本发布流程视图](https://docs.qq.com/flowchart/DVGpndnRmTHdkc3Ji) diff --git a/documentation/7.contribution/release_process_en.md b/documentation/7.contribution/release_process_en.md new file mode 100644 index 000000000000..f64296a18efe --- /dev/null +++ b/documentation/7.contribution/release_process_en.md @@ -0,0 +1,196 @@ +@page page_release_process_en RT-Thread Release Process + +# RT-Thread Release Process + +[中文](https://github.com/RT-Thread/rt-thread/blob/master/documentation/7.contribution/release_process_cn.md) | [Versioning Policy and Implementation Rules](@ref page_release_versioning_en) + +This document describes the six stages of an RT-Thread mainline release, from requirements preparation to publication. See the [Versioning Policy and Implementation Rules](@ref page_release_versioning_en) for version classification, compatibility requirements, and the release checklist. + +## Stage 1: Release Preparation + +### 1. Primary Goal + +- Finalize the development tasks for this release and create a view of the release development tasks. + +### 2. Main Activities + +#### Key Activities + +- Prepare the release draft: review the previous release completion report and development draft to create an initial plan for this release. +- Organize GitHub issues: review unresolved issues from earlier releases, collect issues for new features, and mark them with release labels. + +#### Other Activities + +- Collect requirements from other departments and consolidate functional requirements into a requirements document. +- Evaluate emerging technologies for possible integration into the mainline, recording proposals as issues or discussions. +- Compare the performance of similar products and identify useful features to introduce, recording findings as issues or discussions. + +```mermaid +flowchart TB + A["Release preparation"] --> B["Prepare release draft"] + B --> B1["Previous release completion report"] + B --> B2["Previous release development draft"] + A --> C["Organize GitHub issues"] + C --> C1["Unresolved issues from earlier releases"] + C --> C2["New feature issues"] + A --> D["Collect departmental requirements"] + D --> D1["Functional requirements report with target version"] + A --> E["Evaluate emerging technologies"] + E --> E1["Technology outlook discussions"] + A --> F["Analyze competing products"] +``` + +## Stage 2: Define Initial Goals for the Next Release + +### 1. Primary Goal + +- Define the initial tasks for the next release. + +### 2. Main Activities + +1. Collect community requirements and feedback as issues, starting after the previous release is published. +2. Group the issues into milestones. +3. Define the initial goals for the next release. + +```mermaid +flowchart LR + A["GitHub issues"] --> B["GitHub milestones"] + B --> C["Initial goals for the next release"] +``` + +## Stage 3: Development Preparation + +### 1. Primary Goal + +- Assign development tasks using the release development task view. + +### 2. Main Activities + +- Assign developers to the development tasks for this release. +- Assign reviewers to PRs for different features. + +```mermaid +flowchart TB + A["Development preparation"] --> B["Distribute tasks"] + B --> C["Meet to agree on detailed assignments"] + A --> D["Assign PR reviewers"] + D --> C + D --> E["Kernel"] + D --> F["Drivers"] + D --> G["Components"] + D --> H["BSPs"] + D --> I["CI"] + D --> J["Other areas"] +``` + +## Stage 4: Release Development + +### 1. Primary Goal + +- Track progress and announce the feature freeze in advance. + +### 2. Main Activities + +- Complete the release development goals and record progress in the release plan. +- For core PRs, announce the feature freeze two weeks before release. +- Mark new feature PRs from community developers with GitHub labels. +- Process routine PRs throughout release development. + +```mermaid +flowchart TB + A["Release development"] --> B["Routine PRs throughout mainline development"] + A --> C["Core PRs: announce feature freeze in advance"] + C --> D["Advance release development tasks"] + C --> E["Include community feature PRs identified by GitHub labels"] +``` + +## Stage 5: Pre-release + +### 1. Primary Goal + +- Stabilize features and complete bug regression testing. + +### 2. Main Activities + +#### Core Activities + +- Stabilize the feature set by following up with authors to complete the merging of new feature PRs. +- Complete bug regression testing and collect release issues reported by the community, covering both development and published versions. + +#### Testing + +- Use the release test case template to test different architectures, BSPs, kernels, components, peripherals, file systems, and other areas, and record issues. See the [previous release test case document](https://docs.qq.com/sheet/DYUFZbEdrek1KWFd4). + +#### Reporting + +- Combine release development task progress with a summary of new feature PRs from community developers to produce a release task completion report. + +```mermaid +flowchart TB + A["Pre-release"] --> B["Core activities"] + B --> C["Feature stabilization"] + B --> D["Bug regression testing"] + D --> E["Community-reported issues"] + E --> F["Collect release issues and record version numbers"] + A --> G["Testing"] + A --> H["Reporting"] + H --> I["Release development task progress"] + H --> J["Summary of community feature PRs"] + I --> K["Release task completion report"] + J --> K + F --> K +``` + +## Stage 6: Release Publication + +### 1. Key Activities + +- Publish the version tag and release on GitHub. +- Publish the version tag and release on Gitee. +- Write documentation describing the new features in the release. +- Write the English changelog for the GitHub release. See the [version comparison example](https://github.com/RT-Thread/rt-thread/compare/v5.0.1...v5.0.2). +- Publish the release announcement on the community's WeChat official account. +- Hold a release launch event. + +### 2. Other Activities + +- Publish a community thread inviting developers to discuss the release and provide feedback. +- Update RT-Thread Studio project files and publish projects for the new version. +- Update chip support information on the commercial website, focusing on newly supported architectures. See the [chip support page](https://www.rt-thread.com/products/Chip-39.html). +- Update documentation and links for newly supported features in the [documentation center](https://www.rt-thread.org/document/site/#/). +- Update the cloud download link for RT-Thread source code on the official website. See the [source code download page](https://www.rt-thread.org/download.html#download-rt-thread-source-code). + +```mermaid +flowchart TB + A["Release publication"] --> B["Publish tags and releases"] + B --> B1["GitHub"] + B --> B2["Gitee"] + A --> C["New feature documentation"] + A --> D["Release communications"] + D --> D1["English GitHub release changelog"] + D --> D2["WeChat release announcement"] + A --> E["Release launch event"] + A --> F["Other activities"] + F --> F1["Community feedback thread"] + F --> F2["RT-Thread Studio project updates"] + F --> F3["Commercial website updates"] + F --> F4["Documentation center updates"] + F --> F5["Official source code download link update"] +``` + +## Release Process Overview + +The diagrams above detail the activities within each stage. The overall sequence is: + +```mermaid +flowchart TB + A["1. Release preparation"] --> B["2. Initial goals for the next release"] + B --> C["3. Development preparation"] + C --> D["4. Release development"] + D --> E["5. Pre-release"] + E --> F["6. Release publication"] +``` + +## References + +- [Tencent Docs: Release Process Diagram](https://docs.qq.com/flowchart/DVGpndnRmTHdkc3Ji) diff --git a/documentation/7.contribution/release_versioning_cn.md b/documentation/7.contribution/release_versioning_cn.md new file mode 100644 index 000000000000..7bc6943fd7c0 --- /dev/null +++ b/documentation/7.contribution/release_versioning_cn.md @@ -0,0 +1,212 @@ +# 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 一致。 diff --git a/documentation/7.contribution/release_versioning_en.md b/documentation/7.contribution/release_versioning_en.md new file mode 100644 index 000000000000..839d5421a564 --- /dev/null +++ b/documentation/7.contribution/release_versioning_en.md @@ -0,0 +1,214 @@ +@page page_release_versioning_en RT-Thread Versioning Policy and Implementation Rules + +# RT-Thread Versioning Policy and Implementation Rules + +[中文](https://github.com/RT-Thread/rt-thread/blob/master/documentation/7.contribution/release_versioning_cn.md) | [Release Process](@ref page_release_process_en) + +| Item | Details | +| --- | --- | +| Document version | 1.0 | +| Date | 2026-10-27 | +| Scope | RT-Thread mainline release planning, release publication, and stable branch maintenance | +| Companion document | [Release Process](@ref page_release_process_en) | + +Release cadence: In principle, a `Z` release is published every month. A `Y` release is published every 3–6 months, depending on accumulated features and maintenance resources. `X` releases have no fixed schedule. + +## 1. Version Number Format + +Official releases use the following format: + +```text +vX.Y.Z +``` + +Examples: `v6.0.0`, `v6.1.0`, and `v6.1.1`. + +The version number must be consistent across source version macros, the Git tag, the release, and deliverable names: + +| Item | Example | +| --- | --- | +| Git tag | `v6.1.0` | +| `RT_VERSION_MAJOR` | `6` | +| `RT_VERSION_MINOR` | `1` | +| `RT_VERSION_PATCH` | `0` | + +Routine commits do not increment the official version number. Development snapshots must be identified by the target version, full Git SHA, and build records, and must not be labeled as published official releases. + +## 2. Version Components + +| Component | Purpose | Typical RT-Thread changes | +| --- | --- | --- | +| `X`: major | Major features or an overhaul of the overall technical architecture | A new kernel, reworked core kernel mechanisms, a new device or driver framework, system architecture changes, coordinated upgrades across core subsystems, or major API/ABI or configuration changes requiring user migration | +| `Y`: minor | Feature extensions to the existing kernel and frameworks; released every 3–6 months, depending on accumulated features and resources | New kernel or component APIs, driver framework capabilities, file system or networking capabilities, architecture or chip family support, or a set of BSP or component features that forms a complete deliverable | +| `Z`: patch | Focused fixes, support, and local improvements; in principle, released every month | Bug and security fixes, local feature improvements, performance or resource optimizations, individual BSP adaptations, build fixes, and documentation fixes | + +### 2.1 `X`: Major Version + +An increment of `X` requires a comprehensive review and decision for changes such as: + +- Introducing a new kernel or replacing core kernel mechanisms. +- Introducing a new device model, driver framework, or system-level software framework. +- Coordinating upgrades across multiple core subsystems that change how the system is used as a whole. +- Removing, renaming, or changing public APIs, the ABI, structure layouts, or system call conventions. +- Changing Kconfig, configuration formats, startup sequences, or data formats so that existing projects require migration. +- Delivering a major upgrade in overall capabilities and architecture, even if some APIs remain compatible. + +Related supporting features must be included in the same major release plan. + +### 2.2 `Y`: Minor Version + +Increment `Y` for changes that meet the following conditions: + +- Adding kernel APIs, component APIs, or reusable public capabilities while preserving compatibility with existing interfaces. +- Adding capabilities to driver frameworks, file systems, network stacks, or package frameworks. +- Adding support for an architecture, chip family, or group of BSPs that forms an independently deliverable platform capability. +- Completing several related small features that meet the release goals and form a complete, verifiable, releasable feature set. + +An isolated feature, local parameter extension, or optimization of a single implementation does not automatically trigger a `Y` increment. Features must meet the delivery scope defined by the release milestone and have corresponding test evidence. The `Y` release cycle is 3–6 months; once selected, the specific cycle must be stated in the release goals. Features that cannot complete validation within that cycle must be deferred to the next release. + +### 2.3 `Z`: Patch Version + +Increment `Z` for changes that meet the following conditions: + +- Fixing deadlocks, out-of-bounds access, memory leaks, boot failures, security vulnerabilities, build failures, or performance regressions. +- Improving local functionality, error handling, logging, performance, or resource usage. +- Adding an adaptation for an individual BSP, chip, or platform. +- Fixing documentation, tests, build scripts, or release materials. + +A `Z` release must not introduce new public APIs, complete components, driver frameworks, architectural frameworks, or planned incompatible changes. If an individual BSP introduces a new driver framework, device model, or public API, the change requires a `Y` or `X` increment. + +## 3. Version Classification Priority + +When a release contains multiple types of changes, use the highest impact level to determine its version number: + +```text +X: major > Y: minor > Z: patch +``` + +| Combination of changes | Classification | +| --- | --- | +| Major kernel/framework changes + new components + bug fixes | `X` | +| New component/API/platform capabilities + local fixes | `Y` | +| Bug fixes + individual BSP adaptations + performance optimizations | `Z` | +| Documentation, tests, CI, or release materials only | No official version increment | + +Do not determine version numbers by commit count, PR count, lines of code, or development cycle length. Use feature boundaries, user impact, architectural impact, and completeness of delivery. + +## 4. Implementation Rules by Version Component + +**Basis for release: periodic evaluation + accumulated features.** + +Developers are advised to use `X/Y` releases. `Z` releases serve as intermediate stabilization points for traceability. + +### 4.1 `X` Releases + +To be discussed. + +### 4.2 `Y` Releases + +| Item | Requirement | +| --- | --- | +| Maintenance approach | Manual work + CI, with staffing focused on BSP and driver maintenance | +| Main purpose | Stabilize and release major driver framework and kernel API changes, as well as support for new architectures and frameworks | +| Release frequency | A 3–6 month cycle, with core maintainers reviewing and deciding whether to release | + +**Release strategy:** + +1. CI provides a test checklist and firmware for the corresponding test cases. +2. Testers perform manual validation and upload the results. +3. AI uses prompts or skills to consolidate the results into a release test report. +4. Humans review the report, and core maintainers decide whether to release based on accumulated features and validation results. + +### 4.3 `Z` Releases + +**Prerequisite: the mainline has an initial, reasonably complete automated workflow in place.** + +| Item | Requirement | +| --- | --- | +| Maintenance approach | Primarily QEMU + CI automation | +| Test scope | The kernel, components, and drivers supported by simulation | +| Main purpose | Stabilize the mainline periodically through small releases that support traceability | +| Release frequency | Monthly evaluation, with a human decision on whether to trigger a release | + +**Release strategy:** + +1. CI runs tests automatically and collects test coverage and pass rates. +2. CI generates a release test report covering coverage, pass rates, functionality introduced by commits since the previous release, and known issues. +3. A release proposal discussion is created automatically to notify core maintainers and invite their input. +4. Core maintainers decide whether to release. A release may be skipped if only a few fixes or optimizations have accumulated during the period. + +The overall pass rate does not have to reach 100%, but known issues must be listed so maintainers can assess them before making the release decision. + +## 5. Version Planning Process + +See the [Release Process](@ref page_release_process_en) for release stages and responsibilities. + +```text +A requirement or PR proposes a version classification + -> Module maintainer makes an initial assessment + -> Core maintainer group reviews high-risk changes + -> Changes enter the release milestone + -> X.Y is confirmed before feature freeze + -> X.Y.Z is confirmed before release + -> Release owner creates the tag and release +``` + +### 5.1 Release Preparation + +- Collect unresolved issues from the previous release, community requirements, and new features. +- Assign an initial `X`, `Y`, or `Z` classification based on feature impact. +- Create a release milestone that distinguishes mandatory, deferrable, and excluded items. +- Assign the release owner, module maintainers, target platforms, and test owners. +- Plan `Z` releases backward from a one-month cycle. For `Y` releases, choose a 3–6 month cycle according to feature scope and available resources. Confirm test capabilities and maintenance staffing before defining the feature scope. + +### 5.2 Release Development + +- PRs adding new features must state the proposed version level and the reason for that classification when they are submitted for merging. +- Module maintainers confirm feature boundaries, compatibility, and test scope. +- If an `X`-level change is identified, reassess the release goals, migration cost, and release date. +- If a new feature cannot form a complete deliverable, keep it on the mainline and defer it to the next release. Do not conceal scope changes by changing the version number. +- Maintain only one `Y` release target per release cycle. Do not accept untested large features at the last minute to meet a release date. Defer features that have not completed validation to the next release. + +### 5.3 Feature Freeze + +- Begin stabilizing fixes for a `Z` release approximately one month before release. Begin stabilizing features for a `Y` release approximately one month before release, and confirm `X.Y` before the freeze. +- After the freeze, do not add features, public APIs, components, or framework capabilities. +- After the freeze, allow only fixes for release blockers, necessary security fixes, and corrections to release materials. +- Remove `X`- or `Y`-level changes discovered after the freeze from the current release. Replan them for a major release or the next minor release on a 3–6 month cycle, respectively. + +### 5.4 Official Release + +- Set the release version to `X.Y.0`, or to `X.Y.Z` on a stable branch. +- The release owner checks consistency across version macros, the Git tag, the release, the changelog, and deliverables. +- If an issue is found after publication, publish a new `X.Y.Z+1` release. Do not modify the original tag, release contents, or deliverables. + +### 5.5 Release Cadence + +| Cycle | Main activity | +| --- | --- | +| 1 month | Publish a `Z` release focused on defects, security issues, local optimizations, and BSP adaptations | +| 3–6 months | Publish a `Y` release when its feature set, test scope, and maintenance resources meet the requirements | +| `X` releases | Plan separately according to readiness for kernel, framework, or system-level upgrades, without a fixed cycle | + +No release type requires a fixed publication date. A release may be deferred if blockers remain within its guaranteed support scope. Do not force a release by reducing promised testing, narrowing the support scope, or skipping reviews of high-risk changes. Once the cycle for a `Y` release is selected, do not shorten it to accommodate last-minute features. + +## 6. Compatibility and Migration Requirements + +The following changes require a compatibility review: + +- Public interfaces and behavior of thread scheduling, IPC, timers, memory management, interrupts, or SMP. +- Device driver interfaces, BSP initialization, Kconfig, default configurations, and component configuration formats. +- File systems, network stacks, package APIs, error codes, blocking semantics, and interrupt context restrictions. +- Structure layouts, the ABI, toolchain requirements, default stack sizes, heap layouts, and critical resource usage. + +Compatibility changes must record affected users or components, migration methods, representative BSPs, and known limitations. `X` releases must provide migration instructions. `Y` and `Z` releases must also explicitly document changes to default behavior or resource usage in the release notes. + +## 7. Release Checklist + +- [ ] The release milestone defines mandatory scope and release goals. +- [ ] All included changes have an `X/Y/Z` classification. +- [ ] The core maintainer group has approved all `X`-level changes. +- [ ] `Y`-level features are independently deliverable and have completed testing. +- [ ] `Z`-level changes introduce no new public APIs, complete components, or framework capabilities. +- [ ] No unapproved feature changes have occurred after the freeze. +- [ ] `RT_VERSION_MAJOR/MINOR/PATCH` matches the Git tag. diff --git a/documentation/Doxyfile.1.9.1 b/documentation/Doxyfile.1.9.1 index 50632394df6b..deba1c175355 100644 --- a/documentation/Doxyfile.1.9.1 +++ b/documentation/Doxyfile.1.9.1 @@ -932,6 +932,8 @@ EXCLUDE = ./0.doxygen/mainpage.h \ ./env/env-vscode.md \ ./7.contribution/coding_style_cn.md \ ./7.contribution/bsp_contribution_guide_cn.md \ + ./7.contribution/release_versioning_cn.md \ + ./7.contribution/release_process_cn.md \ ../src/utest/perf/README.md # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or diff --git a/documentation/Doxyfile.1.9.8 b/documentation/Doxyfile.1.9.8 index f19d095008bd..0e0c954655a4 100644 --- a/documentation/Doxyfile.1.9.8 +++ b/documentation/Doxyfile.1.9.8 @@ -1022,6 +1022,8 @@ EXCLUDE = ./0.doxygen/mainpage.h \ ./env/env-vscode.md \ ./7.contribution/coding_style_cn.md \ ./7.contribution/bsp_contribution_guide_cn.md \ + ./7.contribution/release_versioning_cn.md \ + ./7.contribution/release_process_cn.md \ ../src/utest/perf/README.md # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or