1.. _api_lifecycle: 2 3API Lifecycle 4############# 5 6Developers using Zephyr's APIs need to know how long they can trust that a 7given API will not change in future releases. At the same time, developers 8maintaining and extending Zephyr's APIs need to be able to introduce 9new APIs that aren't yet fully proven, and to potentially retire old APIs when they're 10no longer optimal or supported by the underlying platforms. 11 12 13.. figure:: api_lifecycle.png 14 :align: center 15 :alt: API Life Cycle 16 :figclass: align-center 17 18 API Life Cycle 19 20An up-to-date table of all APIs and their maturity level can be found in the 21:ref:`api_overview` page. 22 23 24.. _api_lifecycle_experimental: 25 26Experimental 27************* 28 29Experimental APIs denote that a feature was introduced recently, and may change 30or be removed in future versions. Try it out and provide feedback 31to the community via the `Developer mailing list <https://lists.zephyrproject.org/g/devel>`_. 32 33The following requirements apply to all new APIs: 34 35- Documentation of the API (usage) 36 explaining its design and assumptions, how it is to be used, current 37 implementation limitations, and future potential, if appropriate. 38- The API introduction should be accompanied by at least one implementation 39 of said API (in the case of peripheral APIs, this corresponds to one driver) 40- At least one sample using the new API (may only build on one single board) 41 42When introducing a new and experimental API, mark the API version in the headers 43where the API is defined. An experimental API shall have a version where the minor 44version is up to one (0.1.z). (see :ref:`api_overview`) 45 46Peripheral APIs (Hardware Related) 47================================== 48 49When introducing an API (public header file with documentation) for a new 50peripheral or driver subsystem, review of the API is enforced and is driven by 51the Architecture working group consisting of representatives from different vendors. 52 53The API shall be promoted to ``unstable`` when it has at least two 54implementations on different hardware platforms. 55 56.. _api_lifecycle_unstable: 57 58Unstable 59******** 60 61The API is in the process of settling, but has not yet had sufficient real-world 62testing to be considered stable. The API is considered generic in nature and can 63be used on different hardware platforms. 64 65When the API changes status to unstable API, mark the API version in the headers 66where the API is defined. Unstable APIs shall have a version where the minor 67version is larger than one (0.y.z | y > 1 ). (see :ref:`api_overview`) 68 69.. note:: 70 71 Changes will not be announced. 72 73Peripheral APIs (Hardware Related) 74================================== 75 76The API shall be promoted from ``experimental`` to ``unstable`` when it has at 77least two implementations on different hardware platforms. 78 79Hardware Agnostic APIs 80======================= 81 82For hardware agnostic APIs, multiple applications using it are required to 83promote an API from ``experimental`` to ``unstable``. 84 85.. _api_lifecycle_stable: 86 87Stable 88******* 89 90The API has proven satisfactory, but cleanup in the underlying code may cause 91minor changes. Backwards-compatibility will be maintained if reasonable. 92 93An API can be declared ``stable`` after fulfilling the following requirements: 94 95- Test cases for the new API with 100% coverage 96- Complete documentation in code. All public interfaces shall be documented 97 and available in online documentation. 98- The API has been in-use and was available in at least 2 development releases 99- Stable APIs can get backward compatible updates, bug fixes and security fixes 100 at any time. 101 102In order to declare an API ``stable``, the following steps need to be followed: 103 104#. A Pull Request must be opened that changes the corresponding entry in the 105 :ref:`api_overview` table 106#. An email must be sent to the ``devel`` mailing list announcing the API 107 upgrade request 108#. The Pull Request must be submitted for discussion in the next 109 `Zephyr Architecture meeting`_ where, barring any objections, the Pull Request 110 will be merged 111 112 113When the API changes status to stable API, mark the API version in the headers 114where the API is defined. Stable APIs shall have a version where the major 115version is one or larger (x.y.z | x >= 1 ). (see :ref:`api_overview`) 116 117.. _breaking_api_changes: 118 119Introducing breaking API changes 120================================ 121 122A stable API, as described above, strives to remain backwards-compatible through 123its life-cycle. There are however cases where fulfilling this objective prevents 124technical progress, or is simply unfeasible without unreasonable burden on the 125maintenance of the API and its implementation(s). 126 127A breaking API change is defined as one that forces users to modify their 128existing code in order to maintain the current behavior of their application. 129The need for recompilation of applications (without changing the application 130itself) is not considered a breaking API change. 131 132In order to restrict and control the introduction of a change that breaks the 133promise of backwards compatibility, the following steps must be followed whenever 134such a change is considered necessary in order to accept it in the project: 135 136#. An :ref:`RFC issue <rfcs>` must be opened on GitHub with the following 137 content: 138 139 .. code-block:: none 140 141 Title: RFC: Breaking API Change: <subsystem> 142 Contents: - Problem Description: 143 - Background information on why the change is required 144 - Proposed Change (detailed): 145 - Brief description of the API change 146 - Detailed RFC: 147 - Function call changes 148 - Device Tree changes (source and bindings) 149 - Kconfig option changes 150 - Dependencies: 151 - Impact to users of the API, including the steps required 152 to adapt out-of-tree users of the API to the change 153 154 Instead of a written description of the changes, the RFC issue may link to a 155 Pull Request containing those changes in code form. 156#. The RFC issue must be labeled with the GitHub ``Breaking API Change`` label 157#. The RFC issue must be submitted for discussion in the next `Zephyr 158 Architecture meeting`_ 159#. An email must be sent to the ``devel`` mailing list with a subject identical 160 to the RFC issue title and that links to the RFC issue 161 162The RFC will then receive feedback through issue comments and will also be 163discussed in the Zephyr Architecture meeting, where the stakeholders and the 164community at large will have a chance to discuss it in detail. 165 166Finally, and if not done as part of the first step, a Pull Request must be 167opened on GitHub. It is left to the person proposing the change to decide 168whether to introduce both the RFC and the Pull Request at the same time or to 169wait until the RFC has gathered consensus enough so that the implementation can 170proceed with confidence that it will be accepted. 171The Pull Request must include the following: 172 173- A title that matches the RFC issue 174- A link to the RFC issue 175- The actual changes to the API 176 177 - Changes to the API header file 178 - Changes to the API implementation(s) 179 - Changes to the relevant API documentation 180 - Changes to Device Tree source and bindings 181 182- The changes required to adapt in-tree users of the API to the change. 183 Depending on the scope of this task this might require additional help from 184 the corresponding maintainers 185- An entry in the "API Changes" section of the release notes for the next 186 upcoming release 187- The labels ``API``, ``Breaking API Change`` and ``Release Notes``, as well as 188 any others that are applicable 189- The label ``Architecture Review`` if the RFC was not yet discussed and agreed upon in `Zephyr 190 Architecture meeting`_ 191 192Once the steps above have been completed, the outcome of the proposal will 193depend on the approval of the actual Pull Request by the maintainer of the 194corresponding subsystem. As with any other Pull Request, the author can request 195for it to be discussed and ultimately even voted on in the `Zephyr TSC meeting`_. 196 197If the Pull Request is merged then an email must be sent to the ``devel`` and 198``user`` mailing lists informing them of the change. 199 200The API version shall be changed to signal backward incompatible changes. This 201is achieved by incrementing the major version (X.y.z | X > 1). It MAY also 202include minor and patch level changes. Patch and minor versions MUST be reset to 2030 when major version is incremented. (see :ref:`api_overview`) 204 205.. note:: 206 207 Breaking API changes will be listed and described in the migration guide. 208 209Deprecated 210*********** 211 212.. note:: 213 214 Unstable APIs can be removed without deprecation at any time. 215 Deprecation and removal of APIs will be announced in the "API Changes" 216 section of the release notes. 217 218The following are the requirements for deprecating an existing API: 219 220- Deprecation Time (stable APIs): 2 Releases 221 The API needs to be marked as deprecated in at least two full releases. 222 For example, if an API was first deprecated in release 4.0, 223 it will be ready to be removed in 4.2 at the earliest. 224 There may be special circumstances, determined by the Architecture working group, 225 where an API is deprecated sooner. 226- What is required when deprecating: 227 228 - Mark as deprecated. This can be done by using the compiler itself 229 (``__deprecated`` for function declarations and ``__DEPRECATED_MACRO`` for 230 macro definitions), or by introducing a Kconfig option (typically one that 231 contains the ``DEPRECATED`` word in it) that, when enabled, reverts the APIs 232 back to their previous form 233 - Document the deprecation 234 - Include the deprecation in the "API Changes" of the release notes for the 235 next upcoming release 236 - Code using the deprecated API needs to be modified to remove usage of said 237 API 238 - The change needs to be atomic and bisectable 239 - Add an entry in the corresponding release 240 `GitHub issue <https://github.com/zephyrproject-rtos/zephyr/labels/deprecation_tracker>`_ 241 tracking removal of deprecated APIs. 242 In this example in the one corresponding to the 4.2 release. 243 244During the deprecation waiting period, the API will be in the ``deprecated`` 245state. The Zephyr maintainers will track usage of deprecated APIs on 246``docs.zephyrproject.org`` and support developers migrating their code. Zephyr 247will continue to provide warnings: 248 249- API documentation will inform users that the API is deprecated. 250- Attempts to use a deprecated API at build time will log a warning to the 251 console. 252 253 254Retired 255******* 256 257In this phase, the API is removed. 258 259The target removal date is 2 releases after deprecation is announced. 260The Zephyr maintainers will decide when to actually remove the API: this 261will depend on how many developers have successfully migrated from the 262deprecated API, and on how urgently the API needs to be removed. 263 264If it's OK to remove the API, it will be removed. The maintainers will remove 265the corresponding documentation, and communicate the removal in the usual ways: 266the release notes, mailing lists, Github issues and pull-requests. 267 268If it's not OK to remove the API, the maintainers will continue to support 269migration and update the roadmap with the aim to remove the API in the next 270release. 271 272.. _`Zephyr TSC meeting`: https://github.com/zephyrproject-rtos/zephyr/wiki/Zephyr-Committee-and-Working-Group-Meetings#technical-steering-committee-tsc 273.. _`Zephyr Architecture meeting`: https://github.com/zephyrproject-rtos/zephyr/wiki/Architecture-Working-Group 274
