| .. _api_lifecycle: |
| |
| API Lifecycle |
| ############# |
| |
| Developers using Zephyr's APIs need to know how long they can trust that a |
| given API will not change in future releases. At the same time, developers |
| maintaining and extending Zephyr's APIs need to be able to introduce |
| new APIs that aren't yet fully proven, and to potentially retire old APIs when they're |
| no longer optimal or supported by the underlying platforms. |
| |
| |
| .. figure:: api_lifecycle.png |
| :align: center |
| :alt: API Life Cycle |
| :figclass: align-center |
| |
| API Life Cycle |
| |
| |
| Experimental |
| ************* |
| |
| Experimental APIs denote that a feature was introduced recently, and may change |
| or be removed in future versions. Try it out and provide feedback |
| to the community via the `Developer mailing list <https://lists.zephyrproject.org/g/devel>`_. |
| |
| Peripheral APIs (Hardware Related) |
| ================================== |
| |
| When introducing an API (public header file with documentation) for a new |
| peripheral or driver subsystem, review of the API is enforced and is driven by |
| the API working group consisting of representatives from different vendors. |
| |
| The following requirements apply to new APIs: |
| |
| - Documentation of the API (usage) |
| explaining its design and assumptions, how it is to be used, current |
| implementation limitations, and future potential, if appropriate. |
| - The API introduction should be accompanied by at least one driver |
| implementing this API |
| - At least one sample using the new API |
| |
| The API shall be promoted to ``unstable`` when it has at least two |
| implementations on different hardware platforms. |
| |
| Hardware Agnostic APIs |
| ======================= |
| |
| For hardware agnostic APIs, multiple applications are required to promote an |
| API from ``experimental`` to ``unstable``. |
| |
| |
| Unstable |
| ******** |
| |
| The API is in the process of settling, but has not yet had sufficient real-world |
| testing to be considered stable. The API is considered generic in nature and can |
| be used on different hardware platforms. |
| |
| .. note:: |
| |
| Changes will not be announced. |
| |
| Stable |
| ******* |
| |
| The API has proven satisfactory, but cleanup in the underlying code may cause |
| minor changes. Backwards-compatibility will be maintained if reasonable. |
| |
| An API can be declared ``stable`` after fulfilling the following requirements: |
| |
| - Test cases for the new API with 100% coverage |
| - Complete documentation in code. All public interfaces shall be documented |
| and available in online documentation. |
| - The API has been in-use and was available in at least 2 development releases |
| - Stable APIs can get backward compatible updates, bug fixes and security fixes |
| at any time. |
| |
| .. note:: |
| |
| Incompatible changes will be announced in the release notes. |
| |
| Deprecated |
| *********** |
| |
| .. note:: |
| |
| Unstable APIs can be removed without deprecation at any time. |
| |
| The following are the requirements for deprecating an existing API: |
| |
| - Deprecation Time (stable APIs): 2 Releases |
| The API needs to be marked as deprecated in at least two full releases. |
| For example, if an API was first deprecated in release 1.14, |
| it will be ready to be removed in 1.16 at the earliest. |
| There may be special circumstances, determined by the API working group, |
| where an API is deprecated sooner. |
| - What is required when deprecating: |
| |
| - Mark as deprecated |
| - Document the deprecation |
| - Code using the deprecated API needs to be modified to remove usage of said |
| API |
| - The change needs to be atomic and bisectable |
| - Create a GitHub issue to track the removal of the deprecated API, and |
| add it to the roadmap targeting the appropriate release |
| (in the example above, 1.16). |
| |
| During the deprecation waiting period, the API will be in the ``deprecated`` |
| state. The Zephyr maintainers will track usage of deprecated APIs on |
| ``docs.zephyrproject.org`` and support developers migrating their code. Zephyr |
| will continue to provide warnings: |
| |
| - API documentation will inform users that the API is deprecated. |
| - Attempts to use a deprecated API at build time will log a warning to the |
| console. |
| |
| |
| Retired |
| ******* |
| |
| In this phase, the API is removed. |
| |
| The target removal date is 2 releases after deprecation is announced. |
| The Zephyr maintainers will decide when to actually remove the API: this |
| will depend on how many developers have successfully migrated from the |
| deprecated API, and on how urgently the API needs to be removed. |
| |
| If it's OK to remove the API, it will be removed. The maintainers will remove |
| the corresponding documentation, and communicate the removal in the usual ways: |
| the release notes, mailing lists, Github issues and pull-requests. |
| |
| If it's not OK to remove the API, the maintainers will continue to support |
| migration and update the roadmap with the aim to remove the API in the next |
| release. |
| |