coreboot 版本发布说明与发布管理体系全解析：从索引页到完整发布流程

• 固件
• 嵌入式
• 操作系统
• 驱动开发

本文以 coreboot 仓库中 Documentation/releases/index.md 为线索，系统梳理 coreboot 的版本发布体系：发布说明（Release Notes）的索引结构、三个月一次的发布节奏、从4.x到YY.MM的版本命名演变、完整的发布执行流程（checklist）、发布脚本的实际用法，以及版本分支维护与弃用通知模板。读者读完本文后，既能快速定位任一历史版本的发布说明，也能掌握从选定 commit、生成签名 tarball 到发布分支的完整操作链路。

一、index.md 的定位：发布说明的导航中枢

Documentation/releases/index.md是整个 coreboot 文档体系中所有版本发布说明的唯一入口索引页。它通过 Sphinx 的toctree指令组织内容，将「即将发布的版本」与「全部历史版本」的发布说明文件挂载到文档目录中，例如：

:maxdepth: 1 26.12 - December 2026 <coreboot-26.12-relnotes.md>

maxdepth: 1表示该目录树只展开一层；26.12 - December 2026 <coreboot-26.12-relnotes.md>的写法将「在文档中显示为版本号与月份」的条目映射到仓库根目录下的实际发布说明文件 coreboot-26.12-relnotes.md。

该索引页还明确指出了两份配套文档的作用：

• checklist：发布流程清单（coreboot Release Process），保证一次发布覆盖所有重要事项，并规定 tarball 格式、分支命名等细节；
• template：发布相关的沟通模板，供发布公告、弃用通知等场景使用。

这两份文档与发布说明文件同属Documentation/releases/目录，在 MAINTAINERS 中被划归COREBOOT RELEASES小节，由专门的发布团队（release team）共同维护，目录清单包括Documentation/releases/与util/release/（发布脚本目录）。

二、发布节奏与版本命名体系

coreboot 采用约 3 个月一次的固定发布周期（依据 checklist.md 中的 "When to release" 一节）：若某次发布延期，下一次发布仍将在上次发布之后 3 个月进行，节奏不因延期而顺延。

从索引页的历史版本列表可以清晰看到命名体系的演变：

命名规则要点：从 2024 年 2 月的24.02起，版本号改用YY.MM格式（年份 + 月份）；在此之前的版本使用4.x递增序列（含一次补丁版本4.8.1与一次补丁发布4.20.1）。索引页将26.12单列为 "Upcoming release"，其余全部归入 "Previous releases"，这一区分与发布说明文档自身的"起草中/已定稿"状态一一对应。

三、发布说明的文档结构：以 26.09 为范例

每份正式发布说明（如 coreboot-26.09-relnotes.md）都遵循固定段落结构，这是所有贡献者在提交补丁时同步更新发布说明的协作格式：

1. 头部统计：发布周期内的作者数与合并补丁数，例如 26.09 在 26.06 之后三个月内由 112 位作者（含 28 位首次提交的新人）合并了 1251 个提交；以及本周期的主线总结。
2. Significant or interesting changes：值得完整描述的重大变更，通常以###小节分主题展开，并附 commit hash 便于追溯，例如：
   • 树级输入校验与加固（EDID 解析器拒绝过短缓冲、FDT 头部一致性校验、CBFS/FMAP 边界校验等）；
   • DDR5 SPD 缓存与 TPM 校验（SPD_CACHE_TPM_HASH将 SPD 缓存 SHA-256 存入 TPM NVRAM，哈希不匹配即强制重新训练 MRC）；
   • 固件构建切换到 C23 标准（-std=gnu23，host 工具因兼容性回退）；
   • LPC 通用解码区间改为编译期校验（LPC_IO()辅助宏）；
   • i8259 / virtual-wire ExtINT 初始化重构；
   • Azalia verb 表可读化改造；
   • 共享 CFR 设置菜单与运行时串口控制台；
   • Intel MIPI camera 的 IPU3 ACPI 生成；
   • EFI capsule-on-disk 支持；
   • AMD Turin SoC 成熟化与首块 EPYC 主板（GIGABYTE MZ33-AR1）。
3. Additional coreboot changes：只需一两行描述即可的零散变更汇总。
4. Changes to external resources：工具链版本升级（如 binutils 2.45.1→2.46.1、LLVM 21.1.8→22.1.8）、Git 子模块指针更新（arm-trusted-firmware、blobs、fsp、intel-microcode 等）、外部 payload 更新（GRUB2 2.14、CrabEFI 支持等）。
5. Platform Updates：新增/移除的主板、更新的 SoC 列表、迁移到分支的计划。
6. Statistics：两个版本间的提交数、增删行数、作者数等数据统计。
7. Links and Contact Information：项目官网、下载页、源码管理、文档、issue 跟踪等联系方式。

正在起草的版本（coreboot-26.12-relnotes.md）则保留了相同的骨架，但各节内容以待填项占位（如 "To be filled in immediately before the release by the release team"），并在文件头注明编写约定：使用 Markdown、参照近期发布说明的格式、芯片/主板增删将在发布前统一更新、发布完成前所有变更均标记为 upcoming。这正是 checklist.md 中「发布前一周 Finalize release notes」「发布后填写最终发布说明」等步骤在文档侧的具体体现。

四、发布流程清单（Checklist）：一次发布的完整时间轴

checklist.md 定义了发布执行的完整时间轴，从「发布前约 6 周」到「发布后 7 天」分阶段推进：

关于发布的目的，checklist 明确说明：coreboot 的发布并非面向所有主板的"稳定性认证"（测试遍布各大洲的 100+ 主板不现实），而是规律性的断点——方便多个团队基于有限的 commit 集合同步源码树、便于依据 git 版本号快速判断构建的新旧，同时也是移除旧代码的时间节点（在某版本 X 公告将于 X+1 后移除某特性，X+1 之后的第一个 commit 即可执行移除）。

五、生成与发布：util/release/build-release 脚本详解

发布的核心执行动作由util/release/build-release脚本完成，该脚本位于仓库 util/release/build-release，属于 release team 维护的util/release/目录。

用法：

usage: util/release/build-release <version> <commit id> [username] [gpg key id] Tags a new coreboot version and creates a tar archive version: New version name to tag the tree with commit id: check out this commit-id after cloning the coreboot tree username: clone the tree using ssh://USERNAME - defaults to https:// gpg key id: used to tag the version, and generate a gpg signature

从脚本源码（util/release/build-release）可以看到四个位置参数依次绑定到VERSION_NAME、COMMIT_ID、USERNAME、GPG_KEY_ID。脚本还内置了若干工程化细节：

• 可复现性：强制LC_ALL=C、LANG=C、TZ=UTC0，保证 tar 包内容与时间戳在不同环境下可复现；
• 工具链校验：要求 GNU tar 版本 ≥ 1.28（支持--sort=name），否则直接报错退出；
• 克隆策略：克隆一份全新的 coreboot 树（若在既有 git 仓库内运行，会用--reference+--dissociate复用本地对象以加速）；提供USERNAME时改用ssh://USERNAME@review.coreboot.org:29418/coreboot.git，否则走 https；
• 签名：打 tag 前会提示输入 PGP 密钥口令（若未设置GPG_TTY则自动取当前终端）；
• 产物：脚本运行完成后得到一个新目录及 4 个文件——主 tarball、blobs tarball 及各自的.sig签名文件：

drwxr-xr-x 9 martin martin 4096 Apr 30 19:57 coreboot-4.6 -rw-r--r-- 1 martin martin 29156788 Apr 30 19:58 coreboot-4.6.tar.xz -rw-r--r-- 1 martin martin 836 Apr 30 19:58 coreboot-4.6.tar.xz.sig -rw-r--r-- 1 martin martin 5902076 Apr 30 19:58 coreboot-blobs-4.6.tar.xz -rw-r--r-- 1 martin martin 836 Apr 30 19:58 coreboot-blobs-4.6.tar.xz.sig

历史上的实际调用示例（4.6 发布）：

util/release/build-release 4.6 db508565 Gaumless 3E4F7DF7

六、发布验证、tag 推送与后续交付

从 tarball 验证：运行make what-jenkins-does确认全量构建通过；并用 QEMU 冒烟测试：

cp configs/config.emulation_qemu_x86_i440fx .config make olddefconfig make qemu-system-x86_64 -bios build/coreboot.rom -serial stdio

其中 config.emulation_qemu_x86_i440fx 是仓库 configs/ 目录下现成的 QEMU 配置；同时将 tarball 目录与仓库内容对比，确认无遗漏。

推送签名 tag：发布脚本已在下载的树中生成签名 tag，进入coreboot-X.Y目录执行git push origin X.Y即可（若推错需 force push 覆盖）。推送 tag 是发布流程中"真正的发布动作"。

后续交付：上传 tarball 与.sig文件、更新 sha256sum 清单（用sha256sum -b coreboot-*.tar.xz生成并 diff 校验）、更新下载页、将 crossgcc 源码上传到镜像目录（先用util/crossgcc/buildgcc -u列出脚本实际使用的源码 URL 集合），并基于发布 ID 构建coreboot-sdk与coreboot-jenkins-nodeDocker 镜像作为发布构建机。

七、发布分支的创建与维护

当需要针对某版本做补丁修复时，分支名严禁与 release tag 同名（同名会导致 git 无法区分 tag 与 branch），必须采用X.Y_branch格式：

git checkout 4.8 git checkout -b 4.8_branch git push origin 4.8_branch

后续通过 cherry-pick 移植修复并推送评审：

git cherry-pick c6d134988c856d0025153fb885045d995bc8c397 git push origin HEAD:refs/for/4.8_branch

boards_supported_on_branches.md 记录了各分支上仍在维护的主板清单：被移出 master 的主板并不代表永久消失——可以检出发出移除前的 release/commit 在发布分支上继续构建与更新。按该文档，CI 系统目前为 4.11、4.12、4.14、4.15、4.16、4.18、4.19 等分支配置了构建器，其余分支可按需申请；安全修复可能由项目方负责回移（backport），其余补丁需要使用者自行处理。

八、配套工具脚本：genrelnotes 与 get_new_authors

util/release/目录下还有两个与发布说明直接相关的辅助脚本：

• genrelnotes：在两个版本（tag/分支/commit）之间生成按目录粗略分类的提交清单。用法为util/release/genrelnotes <old_version> <new_version> [release notes file]；脚本依赖git、cloc、rename，且会在执行过程中 checkout 不同版本，因此禁止在个人工作树中直接运行。例如：util/release/genrelnotes origin/4.1 4.2 rnotes.txt。
• get_new_authors：识别两个时间点之间的新贡献者（历史上到new_version为止出现、但到old_version为止未出现的作者名），可选--update自动更新 AUTHORS 文件、--full输出完整名单。用法如util/release/get_new_authors 24.02 25.01。这与发布后 "Update AUTHORS file with any new authors" 的 checklist 步骤一一对应。

九、沟通模板：发布公告与弃用通知

templates.md 专门提供了发布管理相关的沟通模板，重点是**弃用通知（Deprecation notices）**的撰写规范：

• 时机：弃用通知是发布说明的一部分，作为预警——某部分代码将在未来被移除。移除时间点必须距通知发布至少 6 个月，且必须紧接某次发布之后（即该版本仍包含被弃用部分，而其后一个 commit 就可能将其删除）；
• 内容要素：说明移除对象（Thing）、移除理由（通常是新基础设施 X+1 已取代 X）、时间线（Announced here, Thing will be removed right after the release X months out, X >= 6）、受影响设备清单（分 chipset/board 两级列出）；
• 注意事项：历史上弃用通知曾被误读为"我们打算移除主板 A/B/C"，因此模板强调必须区分"计划移除的部分"与"若无行动将连带受影响的部分"，并给出Call to action小节——号召有受影响硬件的开发者联系维护团队、提供迁移示例 commit 指针，明确"若到期限仍未完成迁移，设备将与 Thing 一同移除"（同时也说明可基于实际迁移进度将移除推迟一个版本）。

十、小结：索引页背后是一套完整的发布工程

Documentation/releases/index.md虽然在外观上只是一个目录索引，但它串联起了 coreboot 的整套发布工程：三个月节奏的版本规划、4.x→YY.MM的命名演进、随补丁同步维护的发布说明格式、分阶段执行的 checklist、由 build-release 驱动的自动化打包与 PGP 签名、X.Y_branch分支维护策略，以及面向社区的弃用通知模板。对于想要了解 coreboot 演进历史、参与社区贡献或自己维护发行版分支的开发者，这份索引及配套文档（checklist.md、templates.md、各版本发布说明、boards_supported_on_branches.md）就是最权威、最完整的起点。

• 固件
• 嵌入式
• 操作系统
• 驱动开发