# Zephyr API 生命周期与代码迁移策略
在嵌入式软件开发中,Zephyr 项目的 API 遵循严格的成熟度演进路径:从 Experimental(实验性)到 Unstable(不稳定),再到 Stable(稳定)、Deprecated(弃用)直至 Retired(退役)。开发者需根据这一生命周期制定相应的代码迁移策略,以应对 Breaking API Changes(破坏性变更)。
## 引入破坏性变更的严格流程
当 Stable 状态的 API 必须引入破坏性变更时,社区要求遵循以下具体步骤以确保变更被接受并合并 Pull Request:
1. **提交 RFC Issue**:必须在 GitHub 上创建一个标题为“RFC: Breaking API Change: <subsystem>”的问题。内容需包含问题描述、背景信息、详细提议的变更(如函数调用、设备树、Kconfig 选项等)、依赖关系以及对用户的影响分析。RFC 必须标记为“Breaking API Change”。
2. **架构会议讨论**:RFC 必须在下一场 Zephyr Architecture meeting 上进行讨论,除非有反对意见,否则将予以合并。
3. **邮件通知**:需向 devel mailing list 发送邮件,主题与 RFC Issue 标题一致,并链接到该问题。
4. **社区反馈**:通过 Issue 评论和架构会议收集利益相关者和社区的详细反馈。
5. **提交 Pull Request**:在获得共识后(或同时),提交包含实际代码变更、文档更新、设备树绑定调整及迁移指南条目的 Pull Request。若 RFC 尚未在会议上达成一致,PR 需添加“Architecture Review”标签。
6. **版本升级**:合并 PR 后,API 版本号的主版本号必须递增(X.y.z -> X+1.y.z),次版本和补丁版本重置为 0,以信号表明向后不兼容的变更。
7. **最终通知**:PR 合并后,需向 devel 和 user mailing list 发送邮件通知变更。
## 弃用与迁移策略
对于需要退出的 API,Zephyr 采用“弃用”机制给予缓冲期:
- **时间要求**:Stable API 需在至少两个完整发布周期内标记为 Deprecated。例如,若在 4.0 版本弃用,最早可在 4.2 版本移除。
- **技术实现**:使用编译器宏(如 `__deprecated`)或 Kconfig 选项标记弃用,并在文档中指明替代方案。
- **迁移支持**:在此期间,维护者会监控使用情况,提供警告日志,并协助开发者修改代码以移除对旧 API 的依赖。一旦确认迁移完成且无阻碍,API 将在后续版本中被正式移除(Retired)。
## 实验性与不稳定性阶段的策略
- **Experimental 阶段**:适用于新引入的硬件相关 API。必须提供文档、至少一个实现和一个示例代码。版本号主版本为 0,次版本不超过 1(如 0.1.z)。此时变更频繁,不建议用于生产环境。
- **Unstable 阶段**:当实验性 API 在至少两个不同硬件平台上有实现时,可晋升至此阶段。版本号次版本大于 1(如 0.y.z, y>1)。此阶段 API 已具备通用性,但尚未充分验证,变更可能随时发生。
开发者应始终查阅最新的 API Overview 页面以获取当前所有 API 的成熟度状态,并根据其生命周期阶段调整代码依赖策略。