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