Lines Matching full:the
7 given API will not change in future releases. At the same time, developers
10 no longer optimal or supported by the underlying platforms.
20 An up-to-date table of all APIs and their maturity level can be found in the
31 to the community via the `Developer mailing list <https://lists.zephyrproject.org/g/devel>`_.
33 The following requirements apply to all new APIs:
35 - Documentation of the API (usage)
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)
42 When introducing a new and experimental API, mark the API version in the headers
43 where the API is defined. An experimental API shall have a version where the minor
50 peripheral or driver subsystem, review of the API is enforced and is driven by
51 the Architecture working group consisting of representatives from different vendors.
53 The API shall be promoted to ``unstable`` when it has at least two
61 The API is in the process of settling, but has not yet had sufficient real-world
62 testing to be considered stable. The API is considered generic in nature and can
65 When the API changes status to unstable API, mark the API version in the headers
66 where the API is defined. Unstable APIs shall have a version where the minor
76 The API shall be promoted from ``experimental`` to ``unstable`` when it has at
90 The API has proven satisfactory, but cleanup in the underlying code may cause
93 An API can be declared ``stable`` after fulfilling the following requirements:
95 - Test cases for the new API with 100% coverage
98 - The API has been in-use and was available in at least 2 development releases
102 In order to declare an API ``stable``, the following steps need to be followed:
104 #. A Pull Request must be opened that changes the corresponding entry in the
106 #. An email must be sent to the ``devel`` mailing list announcing the API
108 #. The Pull Request must be submitted for discussion in the next
109 `Zephyr Architecture meeting`_ where, barring any objections, the Pull Request
113 When the API changes status to stable API, mark the API version in the headers
114 where the API is defined. Stable APIs shall have a version where the major
124 technical progress, or is simply unfeasible without unreasonable burden on the
125 maintenance of the API and its implementation(s).
128 existing code in order to maintain the current behavior of their application.
129 The need for recompilation of applications (without changing the application
132 In order to restrict and control the introduction of a change that breaks the
133 promise of backwards compatibility, the following steps must be followed whenever
134 such a change is considered necessary in order to accept it in the project:
136 #. An :ref:`RFC issue <rfcs>` must be opened on GitHub with the following
143 - Background information on why the change is required
145 - Brief description of the API change
151 - Impact to users of the API, including the steps required
152 to adapt out-of-tree users of the API to the change
154 Instead of a written description of the changes, the RFC issue may link to a
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
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
162 The RFC will then receive feedback through issue comments and will also be
163 discussed in the Zephyr Architecture meeting, where the stakeholders and the
166 Finally, and if not done as part of the first step, a Pull Request must be
167 opened on GitHub. It is left to the person proposing the change to decide
168 whether to introduce both the RFC and the Pull Request at the same time or to
169 wait until the RFC has gathered consensus enough so that the implementation can
171 The Pull Request must include the following:
173 - A title that matches the RFC issue
174 - A link to the RFC issue
175 - The actual changes to the API
177 - Changes to the API header file
178 - Changes to the API implementation(s)
179 - Changes to the relevant API documentation
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
187 - The labels ``API``, ``Breaking API Change`` and ``Release Notes``, as well as
189 - The label ``Architecture Review`` if the RFC was not yet discussed and agreed upon in `Zephyr
192 Once the steps above have been completed, the outcome of the proposal will
193 depend on the approval of the actual Pull Request by the maintainer of the
194 corresponding subsystem. As with any other Pull Request, the author can request
195 for it to be discussed and ultimately even voted on in the `Zephyr TSC meeting`_.
197 If the Pull Request is merged then an email must be sent to the ``devel`` and
198 ``user`` mailing lists informing them of the change.
200 The API version shall be changed to signal backward incompatible changes. This
201 is achieved by incrementing the major version (X.y.z | X > 1). It MAY also
207 Breaking API changes will be listed and described in the migration guide.
215 Deprecation and removal of APIs will be announced in the "API Changes"
216 section of the release notes.
218 The following are the requirements for deprecating an existing API:
221 The API needs to be marked as deprecated in at least two full releases.
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,
228 - Mark as deprecated. This can be done by using the compiler itself
231 contains the ``DEPRECATED`` word in it) that, when enabled, reverts the APIs
233 - Document the deprecation
234 - Include the deprecation in the "API Changes" of the release notes for the
236 - Code using the deprecated API needs to be modified to remove usage of said
238 - The change needs to be atomic and bisectable
239 - Add an entry in the corresponding release
242 In this example in the one corresponding to the 4.2 release.
244 During the deprecation waiting period, the API will be in the ``deprecated``
245 state. The Zephyr maintainers will track usage of deprecated APIs on
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
257 In this phase, the API is removed.
259 The target removal date is 2 releases after deprecation is announced.
260 The Zephyr maintainers will decide when to actually remove the API: this
261 will depend on how many developers have successfully migrated from the
262 deprecated API, and on how urgently the API needs to be removed.
264 If it's OK to remove the API, it will be removed. The maintainers will remove
265 the corresponding documentation, and communicate the removal in the usual ways:
266 the release notes, mailing lists, Github issues and pull-requests.
268 If it's not OK to remove the API, the maintainers will continue to support
269 migration and update the roadmap with the aim to remove the API in the next