建立 RT-Thread 版本管理 CI 与发布流程（分阶段实施）

状态： 计划中，未实现
里程碑： 待 B01 盘点后排期

背景

当前版本发布和测试证据主要依赖人工整理，基线容易漂移，Z/Y 版本的发布边界也不够清晰。本 Issue 用于把版本策略落到可运行的 CI、报告和发布任务上：Z 每月生成报告和发布提议，由人工决定是否发布；Y 每 3～6 个月结合硬件验证评审发布。优先推荐开发者使用 X/Y 基线。

本 Issue 只跟踪建设任务，不代表相关能力已实现。文件名为建议，优先复用现有 GitHub Actions、QEMU BSP 和测试框架，不另起多套系统。

目标

• 盘清现有 CI、构建、QEMU、测试框架和硬件验证能力，明确复用/补齐/新增。
• 建立公共配置：测试矩阵、发布策略、已知问题、结果格式。
• 打通 Z 线：基线准备 → 构建 → QEMU 内核/组件测试 → 汇总 → 月报 → 发布提议 → 人工批准发布。
• 打通 Y 线：固定基线固件 → 硬件测试清单 → 人工上传结果 → CI 校验 → 报告草稿 → 人工审核发布。

非目标

• 首期不承诺全平台覆盖，不建设自动硬件实验室，不承诺固定完成期限。
• 未确认 ci/release-policy.yml 前，不启用自动发布。
• QEMU 仿真结论不扩大为实机结论；SPI/I2C、DMA、引脚、时序等未覆盖项交给硬件验证。
• AI 只辅助生成提交摘要或报告草稿，不参与统计计算，也不决定是否发布。

前置条件

• B01 完成现有能力盘点后，再确定责任人、工作量和排期。
• 首轮只选择一个确认可运行的 QEMU BSP，跑通全链路后再扩矩阵。
• 确认 Discussion 分类、通知名单、受保护发布环境和维护者审批机制。

任务清单

公共配置 B01～B05

• B01 盘点现有能力。 列出现有 CI、构建命令、QEMU 启动命令、测试框架、硬件和维护人，交付“复用/补齐/新增”清单。
• B02 建立 ci/test-matrix.yml。 登记 BSP、架构、配置、工具链/QEMU 版本、构建与启动命令、用例 ID、超时、责任人和是否必测。首轮只选一个可运行 QEMU BSP。
• B03 建立 ci/release-policy.yml。 明确 Z 是主线收敛快照还是补丁线，登记来源分支、上次发布标签选择规则、版本递增规则、维护者名单。未确认前不启用自动发布。
• B04 建立 ci/known-issues.yml。 记录 Issue、受影响平台/用例、影响、负责人、复查日期和是否阻断。不允许用宽泛规则忽略所有失败。
• B05 定义结果格式。 统一 JSON/JUnit，至少包含 SHA、配置、用例 ID、状态、耗时、固件校验值和日志链接。缺字段、重复用例、缺失结果不得按通过处理。

Z 线 C01～C08

• C01 基线准备。 编写 ci/prepare_release.py，接收 base_tag、candidate_sha、版本号，校验提交存在、基线关系和版本号未占用；每月生成 manifest.json，下游统一从 manifest 读取 SHA。无新增提交时生成“无变更”提议，由人工决定跳过。
• C02 固件构建。 复用现有构建方式，按矩阵固定工具链、配置和依赖版本；输出 ELF/固件、实际配置、构建日志、依赖清单和 SHA256。构建失败仍上传日志，对应测试标记“未执行：构建失败”，不得从计划分母删除。
• C03 QEMU 内核运行。 编写 ci/run_qemu.py，加载固件、捕获串口，设置启动/单用例/整轮超时并清理进程；复用现有测试框架，解析用例开始/结束标记，不能只看退出码。首批覆盖启动、线程调度、信号量、互斥量、事件、消息队列、定时器、内存分配释放。区分断言失败、崩溃、超时和基础设施异常。
• C04 组件/驱动运行。 根据现有设备模型选首批用例：文件创建/读写/删除、虚拟块设备 I/O、虚拟网卡收发或回环、串口、系统时钟。每组用例提供独立配置、输入数据、预期结果和清理步骤；网络对端由 CI 控制。登记 QEMU 设备模型和未覆盖项。
• C05 结果汇总与门禁。 编写 ci/collect_results.py，上游成功/失败都执行；核对计划与结果分片，缺失项标记未运行。输出通过、失败、超时、跳过、未运行数量，按平台/模块展示。执行覆盖率 = 有运行结论用例数 / 计划用例数；通过率 = 通过数 /（通过+失败+超时）。代码覆盖率仅在工具支持时单独采集。对照已知问题表，新增失败要求维护者定级；必测缺失、启动失败、数据损坏、严重死锁等列为阻断。
• C06 月报与提交功能说明。 编写 ci/generate_release_report.py，生成 Markdown、汇总 JSON 和证据索引；对比上次基线与本次完整 SHA，关联 PR，按内核、组件、驱动、BSP、修复/优化分类，缺标签提交不得遗漏。报告包含版本建议、提交范围、功能说明、指标、已知/新增问题、未测范围和阻断结论。AI 不可用时仍输出基础报告。
• C07 自动发布提议。 建立 Discussion 模板，填写报告、候选 SHA、建议编号、提交摘要、指标、风险和三个决策选项；配置分类和通知名单，按周期与发布类型查重，同周期更新原提议并保留基线变化记录。先实现 dry-run 本地 Markdown，确认模板后再启用远端创建和通知。提议写权限与 PR 测试任务隔离。
• C08 人工批准后发布。 建立手动发布入口，输入提议链接、获批 SHA、manifest 和版本号；使用受保护环境或等效维护者审批，不把普通评论视为授权。核对批准记录、门禁、版本宏、SHA 和产物校验值；版本宏需更改时先提交再测试新基线。创建 Tag、Release，附报告、变更说明和校验值；Z 标为收敛追溯节点，不进入默认推荐入口。重试时校验已有标签 SHA，只补齐缺失步骤。发布报告和产物永久关联版本。

Y 线 C09

• C09 硬件验证。 形成 3～6 个月目标对应的板卡/驱动矩阵，列出板卡、外设、接线、工具、测试人和预计工时，优先本版本变更与保障平台。复用 C01/C02 输出固定基线固件，生成测试清单：用例 ID、烧录/操作步骤、预期结果和上传入口。建立结构化结果模板，测试人通过 PR 或指定入口上传结果和日志，CI 校验 SHA、板卡、用例及附件。复用 C05 汇总人工结果，硬件与 QEMU 分栏，漏测不默认通过。编写报告提示词/SKILL，AI 仅生成草稿，统计由脚本计算。测试负责人审核报告，核心维护者决定发布，复用 C08 执行发布并标识推荐基线。

分批实施

验收标准 / Definition of Done

• 流水线运行期间主线更新不改变本轮基线；错误标签或重复版本在构建前被拒绝。
• 干净 runner 可构建；注入编译错误后构建失败且日志可下载。
• 正常 QEMU 用例逐项输出结果；注入断言失败、死循环、启动失败后均能准确失败、保存日志并退出。
• 每个纳入组件有可运行用例；数据错误和网络超时能被识别，未覆盖设备显示在报告中。
• 删除结果文件会出现漏测；已知失败不从统计删除；未定级新增失败及阻断项不能自动放行。
• 提交列表与 Git 范围一致，每条结论链接证据；即使构建失败也能输出失败报告。
• 重复运行发布提议不重复建帖，提议 SHA 与报告相同；创建提议不会触发正式发布。
• 未审批、SHA 不同、阻断未清、版本宏不匹配均被拒绝；中断重跑不会生成重复版本或改变标签。
• C09 用一块真实板卡跑通全流程；错误 SHA 和缺失用例可被发现。
• 月度定时启用前完整影子运行一轮：生成报告与提议草稿，不实际发布，验证失败检测、漏测处理、审批和中断恢复。

实施约束

• 每项指定 CI/模块/BSP/发布责任人，估算工作量后排期；不先承诺全平台覆盖或固定建设期限。
• PR 仅执行相关快速任务；取消过期运行，复用构建产物，避免多个工作流重复构建。
• 记录 runner 耗时、算力开销和人工维护工时，再扩展矩阵。
• C02～C05 做成可复用任务；C01、C06、C07 可由一个月度工作流串联；C08 单独隔离发布权限。