Zephyr API生命周期简介

Creative Commons
本作品采用知识共享署名
发表于 | 分类于 | | 阅读次数：

本文说明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