发布流程

Zephyr 项目采用基于时间的发布周期，而非功能驱动的发布周期。Zephyr 的各个发布版本汇集了社区中众多贡献者、公司和个人的工作成果。

基于时间的发布流程使 Zephyr 项目能够在最新技术与功能和出色的整体质量之间取得平衡。约 6 个月的发布周期让项目能够协调已实际实现的功能的开发，在保持发布版本整体质量的同时，避免因一两个尚未就绪的功能而延迟发布。

发布阶段概述

每个发布周期都包括一个 开发阶段 ，随后是一个 稳定阶段 。候选发布版本将在稳定阶段创建。

在开发阶段，各类更改均可合并，因此这一阶段称为主分支的 合并窗口 。在稳定阶段，项目及其维护者专注于修复缺陷和编写发布文档。在此期间，通常不接受新功能。主分支在稳定阶段处于 功能冻结 状态。

当前主版本的里程碑可在官方 GitHub Wiki 上查看。以往发布版本的信息可在此处查看。

备注

每个稳定版本发布后，都会为该版本创建一个新的“发布分支”。

例如，Zephyr 稳定版本 v4.4.0 宣布发布后，便创建了新分支 v4.4-branch 。面向 v4.4.x 修订版本（v4.4.1、v4.4.2 等）的提交应以该分支为目标提出。

本页目前尚未详细说明修订版本的发布流程。

合并窗口（开发阶段）

为发布版本打上标签后，发布负责人会开放主分支，供下一个发布周期进行开发。我们将这段时间称为每个发布版本的 合并窗口 或 开发阶段 。在合并窗口期间，任何满足拉取请求合并标准的代码都可以合并到主分支。每个发布版本的大多数更改都在其合并窗口期间完成。

每个发布版本的合并窗口持续约五个月。

合并窗口结束后，发布团队会为即将发布的版本打上第一个 候选发布版本 标签。此时，主分支停止接受大多数功能开发更改，项目进入下一版本的功能冻结阶段。下一节将介绍功能冻结。

以下是合并窗口的时间线示例：

2025 年 11 月 13 日打上 v4.3.0 标签时，合并窗口开启。此时，主分支开始接受面向下一个发布版本 v4.4.0 的合并。
2026 年 3 月 24 日打上 v4.4.0-rc1 标签时，v4.4.0 的合并窗口关闭。此时，项目进入 v4.4.0 版本的功能冻结阶段。

功能冻结（稳定阶段）

打上第一个候选发布版本标签时，该发布版本的合并窗口随即关闭。这称为该发布版本的 功能冻结 或 稳定阶段 。在功能冻结期间，未经技术指导委员会（TSC）批准破例，不得为该发布版本合并任何新功能。

在稳定阶段，请耐心等待新功能拉取请求的审查。

如前所述，在功能冻结期间合并功能的例外流程需要提供正当理由并获得 TSC 批准。一般而言，如果功能冻结已宣布，而您的拉取请求尚未合并，最好等待下一个合并窗口开启。

如果您认为自己的功能值得破例，应在功能冻结期间合并，请联系 TSC。常用联系信息请参阅 TSC wiki 页面。

以下是功能冻结的时间线示例：

2026 年 3 月 24 日打上 v4.4.0-rc1 标签时，v4.4.0 的功能冻结开始。此时，新功能需要获得 TSC 的例外批准才能合并到主分支。
2026 年 4 月 14 日打上 v4.4.0 标签时，v4.4.0 的功能冻结结束。此时，主分支再次开放，进入下一个发布版本的合并窗口。

以下各节将更详细地介绍功能冻结。

允许的更改

进入功能冻结后，必须将接受的更改仅限于与稳定性相关的更改：

修复功能缺陷
提高可靠性、构建稳定性或改善测试行为的稳定化修复
文档更新（澄清、纠正、改进）
针对现有功能的测试（不启用新功能）

有关何时接受特定变更的更多详情，请参阅表格。

超出上述允许范围的变更极少获得例外许可，且必须提供明确理由并获得 TSC 批准。一般而言，如果某项功能错过了开发阶段的时间窗口，就应等待下一个开发周期。

不允许的变更

功能冻结后不得接受以下变更：

新功能或功能增强
API 变更，除非为解决严重缺陷所必需
与缺陷修复或稳定化工作无直接关联的重构
新增子系统、驱动、开发板，或进行架构变更

功能冻结期间的问题跟踪

功能冻结期间，建议在拉取请求中引用 GitHub issue，但 不作强制要求 。

拉取请求必须清楚说明以下内容：

要解决的问题
该问题的影响
此变更如何解决该问题

当拉取请求的意图或范围不明确时，维护者和发布工程师可以要求进一步说明。

强制使用 issue 的情形

以下情况必须提供 GitHub issue：

阻碍发布的问题
针对已发布分支的维护性修复

审查与批准

所有拉取请求必须遵循标准的审查和批准流程。

维护者必须确保：

变更符合本政策
变更范围尽可能小，且专注于稳定化
风险与当前发布阶段相适应

发布工程师可以：

根据风险评估拒绝或推迟变更
要求修改或提供进一步的理由

风险要求

稳定阶段接受的变更必须满足以下要求：

变更范围尽可能小
风险低
经过充分测试

引入重大风险的变更可以推迟到后续版本，即使这些变更属于错误修复。

拉取请求合并标准

以下标准适用于所有发布阶段。

必须满足所有 PR 要求。
至少获得 2 个批准，其中必须包括指定负责人的批准。
拉取请求应由每个受影响领域的至少一名维护者或协作者审查；如果对某个领域的变更被认为足够简单，则获得其他受影响子系统的维护者或协作者的批准即可。
组织层面的双人复核原则。我们已经要求至少获得 2 个批准（基本的双人复核原则），但如果提交者与批准者来自同一组织，这些审查和批准可能会无意中带有偏见。为了让整个项目的参与者都有机会审查和批准，合并标准增加了以下准则：
- 对通用代码和共享代码的修改或新增必须获得不同组织的批准（至少有一个批准来自提交者所属组织之外的组织）。通用代码和共享代码是指不属于 soc 、 boards 和 drivers/*/* 的所有代码。
- 对硬件支持（驱动、SoC、开发板）的修改或新增，至少必须由来自不同组织的人员执行合并。这仅适用于支持厂商特定硬件的 API 实现，不适用于 API 本身。
- 对于贡献主要来自同一组织且无法由其他组织审查的领域，发布工程师可以允许例外，但合并必须由来自不同组织的人员完成。在这种情况下，必须严格遵守至少 2 天的最短审查期，以便其他人员参与审查。
- 发布工程师不得合并由其所属组织提交且仅由该组织审查的代码变更。要合并此类变更，必须至少有一次审查来自其他组织。
最短审查期为 2 个工作日，简单变更为 4 小时（参见在合并代码前为审查者留出审查时间）。
紧急修复可在 CI 通过后随时合并，不受上述大多数条件的限制。
所有必需的检查均已通过：
- 设备树
- 文档
- 代码静态检查工具（Gitlint、Pylint、Ruff、Sphinx 等）
- 身份/电子邮件地址
- Kconfig
- 许可证检查
- Checkpatch（编码风格）
- 在仿真/模拟平台上进行集成测试（通过 twister）
- 蓝牙模拟测试

发布质量标准

主要目的是明确发布版本必须满足的标准。这有助于用大多数人都能理解的方式界定一个版本何时算是“完成”，也有助于新参与者理解流程并参与成功版本的发布工作：

发布标准记录了目标受众对每个 Zephyr 版本的所有要求
各版本的目标受众可能不同，也可能存在重叠
任何时候，发布标准都不是一成不变的：可能存在遗漏的要求，也可能出现新的要求，在这些情况下，应扩充发布标准，确保涵盖所有需求。

每个版本都必须满足以下总体标准：

不存在阻塞性缺陷或阻塞性问题
所有相关测试均须在 Tier 0 平台上通过
所有相关测试均须在 Tier 0 和 Tier 1 平台上通过（每种架构、架构变体和硬件特性至少覆盖一个平台）
所有适用的示例和测试均须在 Tier 0、Tier 1 和 Tier 2 平台上构建成功
所有高危和严重级别的静态分析问题及安全问题均已解决
发行说明已更新至最新状态。

阻塞性缺陷

阻塞性缺陷处理流程在发布过程中启动，并在功能冻结里程碑之后生效。标记为阻塞性的问题会直接阻止版本发布。在创建发布版本之前，必须解决所有阻塞性缺陷。

对于被授予 blocker 状态的缺陷，其修复在最终发布日期之前的任何时候都可以合入“main”分支并纳入该版本。

严重程度为中等及以上且影响所有用户的缺陷，通常是升级为阻塞性缺陷的候选对象

贡献者和发布工程团队成员应遵循以下发布阻塞性缺陷处理准则：

只有当软件（Zephyr）绝不能在存在该缺陷的情况下发布时，才将其标记为阻塞性缺陷。
所有协作者都可以添加或移除阻塞标签。
根据缺陷的严重程度和影响范围，评估其是否应被列为阻塞性缺陷。
每次添加或移除阻塞标签时，都应提供详细理由。
确保所有阻塞性缺陷都已设置里程碑。
发布经理对阻塞状态拥有最终决定权；如有任何疑问，请联系他们。

Release Milestones

此表记录了每个版本的相关里程碑。

发布里程碑
时间安排	检查点	描述	负责人
T-5M	规划	确定发布日期，指定发布负责人，并就本次发布的项目整体目标达成一致。	TSC
T-7W	审查目标里程碑	最终确定正在开发的功能的目标里程碑。	发布工程
T-5W	发布公告	发布负责人宣布功能冻结和发布时间表。	发布经理
T-4W	发布时间表提醒	发布负责人发送功能冻结和发布时间表的提醒。	发布经理
T-3W	功能冻结（RC1）	RC1 之后，不得引入新功能。仅允许进行稳定性改进、外观调整、缺陷修复、文档改进，以及为现有功能添加新测试。	发布工程
T-2W	第二个候选发布版本	RC2 之后，不得引入新功能，仅允许进行稳定性改进、外观调整、缺陷修复和文档修正。	发布经理
T-1W	严格冻结（RC3）	RC3 之后，仅允许修复阻塞发布的缺陷、改进文档和修改发行说明。发行说明需在此检查点之前完成，并满足发布标准。	发布经理
T-0W	发布		发布经理

长期支持（LTS）版本

长期支持版本旨在获得长期的支持和维护，是推荐用于产品的版本，也是用于认证的可审计分支。

LTS 版本定义如下：

面向产品
延长稳定化阶段 ：留出更多时间进行测试和缺陷修复
稳定的 API
质量驱动的流程
长期维护 ：提供长期维护（至少 5 年）。

面向产品

Zephyr LTS 为产品开发者提供延长的支持和维护服务，涵盖整体稳定性改进、缺陷修复和安全修复，是推荐用于产品开发的版本。

LTS 同时包含成熟功能和新功能。API 和功能的成熟度均有文档记录并持续跟踪。从一个 LTS 版本演进到下一个版本时，成熟稳定的 API 的覆盖范围会不断扩大，让用户能够使用最前沿的功能和新硬件，同时保有随时间演进的稳定基础。

延长的稳定化周期

Zephyr LTS 的开发周期与常规版本不同，其稳定化周期更长。常规版本在计划发布日期前 3 至 4 周冻结功能。LTS 的稳定化周期延长了 3 周，在预计发布日期前 6 至 7 周冻结功能。因此，代码冻结到发布日期之间的时间也相应延长。

稳定的 API

Zephyr LTS 为产品开发提供稳定且长期可用的基础。为保证 API 及其实现的稳定性，构成操作系统核心的所有待发布软件都必须经过 Zephyr API 生命周期，并经历至少 2 个版本的稳定化过程。这确保了发布的许多重点功能和核心功能具有成熟、完善的实现，以及在该 LTS 版本整个生命周期内获得支持的稳定 API。

API 冻结（LTS - 2）
- 所有稳定 API 都需要在 LTS 之前的第 2 个版本中冻结。可以为 API 扩展新功能，但不得修改其核心实现。例如，这一要求适用于以下子系统：
  - 设备驱动程序（i2c.h、spi.h）等
  - 内核（k_*）：
  - 操作系统服务（日志记录、调试等）
  - DTS：API 和绑定的稳定性
  - Kconfig
- 实验性功能的新 API 可以随时添加，前提是它们相互独立，且在文档中明确标记为实验性或不稳定的功能/API。
功能冻结（LTS - 1）——不得添加新功能，也不得对涉及 LTS 主要功能的代码进行大规模改造或重构。
- 内核 + 基础操作系统
- 其他对外宣称的 LTS 功能
- 可以随时添加构建于基础操作系统和对外宣称的 LTS 功能之上，或对其进行扩展的辅助功能，并应在适用时将其标记为实验性功能。

质量驱动的流程

Zephyr 项目遵循行业标准和流程，致力于提供注重质量的版本。为实现这一目标，项目提供以下交付物，用于跟踪所提供软件组件的进展、完整性和质量：

遵循已发布的编码指南、风格指南和命名约定，并记录偏离情况。
静态分析报告
- 使用可用的商业和开源工具，定期对整个代码树进行静态分析，并记录偏离情况和误报。
有文档说明的组件和 API
需求目录
验证计划
验证报告
覆盖率报告
需求追溯矩阵（RTM）
SPDX 许可证报告

每个版本发布时都会提供上述产物，以记录软件发布时的质量和状态。

长期支持与维护

LTS 版本每 2.5 至 3 年发布一次，并建立独立于主代码树的分支，在发布后维护约 5 年。

支持分为三个主要阶段：

阶段 1（前 2 年）： 常规错误修复和安全修复，包括平台和驱动修复。
阶段 2（随后的 3 年以上）： 仅提供安全修复和操作系统稳定性修复。
阶段 3： 第三方可能提供延长支持（详情待定）。

对某个 LTS 版本（LTS N ）的支持将持续到其后第二个 LTS 版本（LTS N+2 ）的初始版本发布。LTS N 的最终版本将在 LTS N+2 的初始版本发布后不久发布。

当前受支持的 LTS 版本列表及其生命周期终止（EOL）日期可在此处查看。

        gitGraph
    commit id: "3.5"
    commit id: "3.6"
    commit id: "3.7"
    branch "LTS"
    checkout "LTS"
    commit id: "3.7.1"
    commit id: "3.7.2"
    checkout main
    commit id: "4.0"
    commit id: "4.1"

长期支持版本

变更和修复会双向流动。不过，从主分支引入 LTS 分支的变更将仅限于同时适用于两个分支且仅涉及现有功能的修复。

针对 LTS 分支的所有修复，如果也适用于主线代码树，则必须同时提交到主线代码树。

可审计代码库

可审计代码库将基于 Zephyr 操作系统的一组明确界定的功能子集建立，且范围有限。审计分支创建后，LTS、开发代码树和可审计代码库应保持同步，但向用于认证的审计分支添加新功能时，须遵循更严格的流程。

新功能引入可审计代码库之前，将执行此流程。

初始及后续认证目标将由 Zephyr 项目理事会决定。

为获得选定认证而需遵循的流程，将由信息安全与功能安全工作组确定，并与 TSC 协调。

主机工具支持政策

本节介绍开发 Zephyr 应用所需主机工具的相关政策。

Python 版本政策

Zephyr 在确定其支持的最低 Python 版本时，会参考 Python upstream release schedule 。

选择最低支持版本时，会兼顾长期支持，以及该版本在主流且仍获积极维护的 Linux 发行版（例如当前的 Ubuntu LTS 和 Debian Stable 版本）中的实际可用性。

当满足以下条件时，会考虑移除对某个 Python 版本的支持：

该版本即将或已经达到上游生命周期终止（EOL）日期，并且
较新的 Python 版本已在当前仍获积极维护的主要 Linux 发行版中广泛可用。

硬件支持等级

本节介绍硬件平台支持等级的大致划分。目前尚未在开发板、架构或 SoC 层面正式执行这些标准或据此进行评估。

等级 0：仿真平台

在 CI 中，测试会在这些平台上构建并运行，因此运行时失败可能阻止拉取请求合并。
由 Zephyr 项目自身提供支持，并承诺修复发布版本中的错误。
每个新架构都必须有一个 Tier 0 平台。
针对该级别平台报告的缺陷应作为 Zephyr 的一般缺陷进行评估和处理，并应以最高优先级处理。

Tier 1：受支持的平台

由特定团队承诺，使用开源且公开可用的驱动程序，定期通过 twister 设备测试运行“Zephyr 兼容性测试套件”（细节待定）。
承诺在版本发布前及时修复缺陷。不由“Zephyr 项目”本身提供支持。
可公开购买
针对该级别平台报告的缺陷应作为 Zephyr 的一般缺陷进行评估和处理，并应以中到高优先级处理。

Tier 2：社区平台

上游已包含平台实现，但不承诺进行测试，且平台可能无法公开获取。
有专门的维护者，承诺回应问题和审查补丁。
针对该级别平台报告的缺陷不视为 Zephyr 的一般缺陷。

Tier 3：已弃用且不受支持的平台

已有平台实现，但没有负责人，或负责人不作回应。
不提供任何支持承诺。
如果无人将其提升至 Tier 2 或更高级别，则可能从上游移除。
针对该级别平台报告的缺陷不视为 Zephyr 的一般缺陷。

发布流程

本节记录发布经理的职责，为发布经理提供知识库。

发布检查清单

每次发布都有一个关联的 GitHub 议题，其中包含完整的检查清单。一次发布完成后，会为下一次发布创建检查清单。

创建标签

Git 中的发布版本和标签应使用以下格式：

发布版本 [主版本号].[次版本号].[补丁级别]
候选发布版本 [主版本号].[次版本号].[补丁级别]-rc[候选版本编号]
标签格式：
- v[Major].[Minor].[Patch Level]-rc[RC Number]
- v[Major].[Minor].[Patch Level]
- v[Major].[Minor].99 - 在 main 分支上创建的标签，表示 v[Major].[Minor+1] 的开发工作已经开始。例如，v1.8 开发流程开始时会创建 v1.7.99 标签。此标签与为开发中的 main 分支版本定义的 VERSION_MAJOR/VERSION_MINOR/PATCHLEVEL 宏相对应。有了此标签，便可在 main 分支上使用“git describe”生成有意义的输出，这通常用于自动构建和 CI 工具。

最终发布版本和每个候选发布版本都应按以下步骤创建标签：

备注

必须通过显式执行 git 命令来创建标签，而不能通过 GitHub 的发布界面创建。GitHub 发布界面不会生成附注标签（无论是正式发布还是预发布，它都会生成“轻量”标签）。你还应将 gpg 公钥上传到 GitHub 账户，因为以下操作涉及创建签名标签。如果没有 gpg 密钥，也可以使用 ssh 密钥进行签名。

备注

本节以创建 1.11.0-rc1 标签为例，请替换为相应的候选发布版版本号。

更新 Git 仓库根目录下 VERSION 文件中的版本变量，使其与此候选发布版的版本号一致。EXTRAVERSION 变量用于指定此候选发布版的 rc[RC Number] 值:
```
EXTRAVERSION = rc1
```
提交包含更新后的 VERSION 文件的 PR，使用 release: Zephyr 1.11.0-rc1 作为提交标题。CI 成功通过后合并该 PR。

使用附注标签为该版本创建标签并推送:

$ git pull
$ git tag -s -m "Zephyr 1.11.0-rc1" v1.11.0-rc1

验证标签是否已正确签名，针对该标签执行 git show 的输出必须包含签名（在输出中查找 BEGIN PGP SIGNATURE 或 BEGIN SSH SIGNATURE 标记）:
```
$ git show v1.11.0-rc1
```

推送标签:

$ git push git@github.com:zephyrproject-rtos/zephyr.git v1.11.0-rc1

向邮件列表（announce 和 devel ）发送电子邮件，并附上该发布版的链接

备注

本节以创建 1.11.0 标签为例，请替换为相应的正式发布版版本号。

当所有正式发布条件均已满足，且最终的发行说明已获批准并合并到仓库后，按照以下流程设置正式发布版版本号并为仓库创建标签：

更新 Git 仓库根目录下 VERSION 文件中的版本变量。将 EXTRAVERSION 变量设置为空字符串，以表示正式发布版:
```
EXTRAVERSION =
```
提交包含更新后的 VERSION 文件的 PR，使用 release: Zephyr 1.11.0 作为提交标题。CI 成功通过后合并该 PR。
使用两个附注标签为该版本创建标签并推送:
```
$ git pull
$ git tag -s -m "Zephyr 1.11.0" v1.11.0
```
验证标签是否已正确签名，针对该标签执行 git show 的输出必须包含签名（在输出中查找 BEGIN PGP SIGNATURE 或 BEGIN SSH SIGNATURE 标记）:
```
$ git show v1.11.0
```

推送标签:

$ git push git@github.com:zephyrproject-rtos/zephyr.git v1.11.0

在发布页面顶部找到新建的 v1.11.0 标签，使用 Edit tag 按钮编辑该发布版，具体如下：
- 将 docs/releases/release-notes-1.11.rst 中的概述复制到发行说明文本框中，并添加指向 docs.zephyrproject.org 上完整发行说明文件的链接。
向邮件列表（announce 和 devel ）发送电子邮件，并附上该发布版的链接