Zephyr API生命周期简介

本文说明Zephyr API的生命周期。

概述 链接到标题

Zephyr是一个优秀的开源嵌入式操作系统，其优秀也体现在开源项目管理上。一个操作系统不断的演进必然会有代码不断的更新，同时也不可避免的API发生变化，API的变化会对使用者和开发者带来一列问题： API的使用者不清楚一个API在将来的某个release版本中是否还会存在，或者API会存在多久。因此无法评估出何时更新到某个release版本，以及更新到某个release版本在API修改上的工作量。 开发者无法决定何时将引入新的或者废弃旧的API，导致新的API无法及时被其它开发者使用测试，废弃的API不能及时被移除。 为解决上述问题，Zephyr的项目管理者定义了Zephyr API的生命周期用于管理API的变化，并有专门的API工作小组负责在每周二召开**Zephyr API meeting **讨论API的变化。 https://github.com/zephyrproject-rtos/zephyr/projects/18 https://github.com/zephyrproject-rtos/zephyr/projects/15

API生命周期 链接到标题

下图是zephyr官网上给出的API生命周期图 life

实验状态(Experimental) 链接到标题

Experimental API表示该API是最近才引入，将来可能会更改或删除。可以尝试使用，并通过maillist向社区反映问题。 新增加一个API的要求:

  1. 提供API文档，说明API的设计原理，使用方法，当前实现的限制以及将来可能的发展
  2. 新添加的API必须被实现
  3. 至少有一个API的使用例子

非稳定状态(Unstable) 链接到标题

Unstable API是指已经被实现，但没有经过足够多的实际测试来确定其稳定性。 Unstable API被认为是通用的，可以在不同的硬件平台上使用。 API满足以下要求时Experimental升级为Unstable：

  • 硬件相关的API(例如设备驱动)，如果在两个或以上不同的硬件平台上被实现，将由Experimental转为Unstable
  • 硬件无关的API，有多个应用程序需要使用该API时，将由Experimental转为Unstable

稳定状态(Stable) 链接到标题

Stable API是已被大量验证，只会较少的修改底层代码，并保存兼容。 满足下面要求时Unstable可升级为Stable:

  • API的测试用例能达到100%覆盖
  • 完整API文档，所有的公共接口必须有文档，并可以在在线文档中查阅到
  • 该API至少在2个开发版release中被使用
  • 更新,bug fixed和security fixed API后需要保证向后兼容

步骤 链接到标题

实际要声明API Stable，需要提交PR,到maillist上宣布API升级请求，在API会议上提交请求，会议上讨论通过后才会merge PR

非兼容修改 链接到标题

API在stable期间要保证向后兼容，但是在某些情况下为继续兼容的工作会带来更大的问题(无法技术升级, 维护工作量大)，这就要求修改Stable API。修改Stable API有更为严苛的要求，会要求提RFC issue，社区反馈，通知所有利益相关人员，然后API meeting和TSC meeting审议。详细步骤不做介绍，可见文末参考。

弃用状态(Deprecated) 链接到标题

当一个API准备被弃用时，在真正的移除前处于弃用等待期，被称为弃用状态 弃用API时间节点

  • 在至少两个完整的发型版中API被标记为Deprecated，该API将被弃用。例如1.14和1.15都将API标为Deprecated， 1.16就可以将其弃用 弃用API要做的动作:
  • 代码中做Deprecated标记,函数使用__deprecated ，宏使用__DEPRECATED_MACRO
  • 弃用文档
  • 修改使用要弃用API的代码,修改必须是原子性的
  • github上提交issue跟踪弃用API

弃用等待期,API处于弃用状态，需要

  • API文档上提示弃用警告
  • 构建时在log中提示弃用警告

退出状态(Retired) 链接到标题

在该阶段API将被删除。 API删除的目标日期是宣布弃用API后的两个发型版，由Zephyr的维护人员决定何时删除，如果无法删除，将更新路线图，并在下一个发行版中删除。当API被删除后，维护者将删除API相关文档。

当前API状态 链接到标题

当前Zephyr版本为2.3.99，下表是摘自Zephyr的官方文档展示了目前API的状态，可以看到76%的API都是稳定的，在使用中应注意管理和控制自己应用代码中的实验性和非稳定API的情况下大可放心使用。 API

参考 链接到标题

https://docs.zephyrproject.org/latest/reference/overview.html https://docs.zephyrproject.org/latest/development_process/api_lifecycle.html#api-lifecycle https://docs.zephyrproject.org/latest/development_process/proposals.html#rfcs