doc: api: Clean up and reorganize a bit
Move the section describing the requirements for a new API out of the peripheral API header, clarify the requirements for upgrading an API to experimental and unstable clearly in the corresponding sections. Add a link to the API stability page. Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
This commit is contained in:
parent
d1512f2da0
commit
b6ee5fca8e
1 changed files with 23 additions and 16 deletions
|
@ -17,6 +17,8 @@ no longer optimal or supported by the underlying platforms.
|
|||
|
||||
API Life Cycle
|
||||
|
||||
An up-to-date table of all APIs and their maturity level can be found in the
|
||||
:ref:`api_stability` page.
|
||||
|
||||
Experimental
|
||||
*************
|
||||
|
@ -25,6 +27,15 @@ 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>`_.
|
||||
|
||||
The following requirements apply to all 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 implementation
|
||||
of said API (in the case of peripheral APIs, this corresponds to one driver)
|
||||
- At least one sample using the new API (may only build on one single board)
|
||||
|
||||
Peripheral APIs (Hardware Related)
|
||||
==================================
|
||||
|
||||
|
@ -32,25 +43,9 @@ 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
|
||||
********
|
||||
|
||||
|
@ -62,6 +57,18 @@ be used on different hardware platforms.
|
|||
|
||||
Changes will not be announced.
|
||||
|
||||
Peripheral APIs (Hardware Related)
|
||||
==================================
|
||||
|
||||
The API shall be promoted from ``experimental`` to ``unstable`` when it has at
|
||||
least two implementations on different hardware platforms.
|
||||
|
||||
Hardware Agnostic APIs
|
||||
=======================
|
||||
|
||||
For hardware agnostic APIs, multiple applications using it are required to
|
||||
promote an API from ``experimental`` to ``unstable``.
|
||||
|
||||
Stable
|
||||
*******
|
||||
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue