blob: 422aa43d94e1dec1c4fbc2c241d49a1dcc3e742a [file] [log] [blame]
Martí Bolívar4ba332a2020-03-20 11:10:02 -07001.. _api_overview:
Carles Cufi39930ca2020-02-19 19:03:03 +01002
Martí Bolívar4ba332a2020-03-20 11:10:02 -07003API Overview
4############
Carles Cufi39930ca2020-02-19 19:03:03 +01005
Martí Bolívar4ba332a2020-03-20 11:10:02 -07006The table lists Zephyr's APIs and information about them, including their
Fabio Baltieri2875f002022-10-03 11:26:34 +00007current :ref:`stability level <api_lifecycle>`. More details about API changes
8between major releases are available in the :ref:`zephyr_release_notes`.
Carles Cufi39930ca2020-02-19 19:03:03 +01009
Ederson de Souza9ab243d2023-08-25 13:58:52 -070010The version column uses `semantic version <https://semver.org/>`_, and has the
11following expectations:
Martí Bolívar2485d762020-10-27 13:09:07 -070012
Ederson de Souza9ab243d2023-08-25 13:58:52 -070013 * Major version zero (0.y.z) is for initial development. Anything MAY
14 change at any time. The public API SHOULD NOT be considered stable.
Carles Cufi39930ca2020-02-19 19:03:03 +010015
Ederson de Souza9ab243d2023-08-25 13:58:52 -070016 * If minor version is up to one (0.1.z), API is considered
17 :ref:`experimental <api_lifecycle_experimental>`.
18 * If minor version is larger than one (0.y.z | y > 1), API is considered
19 :ref:`unstable <api_lifecycle_unstable>`.
Carles Cufi39930ca2020-02-19 19:03:03 +010020
Ederson de Souza9ab243d2023-08-25 13:58:52 -070021 * Version 1.0.0 defines the public API. The way in which the version number
22 is incremented after this release is dependent on this public API and how it
23 changes.
Martí Bolívar2485d762020-10-27 13:09:07 -070024
Ederson de Souza9ab243d2023-08-25 13:58:52 -070025 * APIs with major versions equal or larger than one (x.y.z | x >= 1 ) are
26 considered :ref:`stable <api_lifecycle_stable>`.
27 * All existing stable APIs in Zephyr will be start with version 1.0.0.
Carles Cufi39930ca2020-02-19 19:03:03 +010028
Ederson de Souza9ab243d2023-08-25 13:58:52 -070029 * Patch version Z (x.y.Z | x > 0) MUST be incremented if only backwards
30 compatible bug fixes are introduced. A bug fix is defined as an internal
31 change that fixes incorrect behavior.
Carles Cufi39930ca2020-02-19 19:03:03 +010032
Ederson de Souza9ab243d2023-08-25 13:58:52 -070033 * Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards
34 compatible functionality is introduced to the public API. It MUST be
35 incremented if any public API functionality is marked as deprecated. It MAY
36 be incremented if substantial new functionality or improvements are
37 introduced within the private code. It MAY include patch level changes.
38 Patch version MUST be reset to 0 when minor version is incremented.
Jamie McCrae71e7cf82023-01-15 12:35:24 +000039
Ederson de Souza9ab243d2023-08-25 13:58:52 -070040 * Major version X (x.Y.z | x > 0) MUST be incremented if a compatibility
41 breaking change was made to the API.
Carlo Caionef5c66e92023-05-30 17:04:08 +020042
Ederson de Souza9ab243d2023-08-25 13:58:52 -070043.. note::
44 Version for existing APIs are initially set based on the current state of the
45 APIs:
Jamie McCrae3205a582023-09-27 09:37:35 +010046
Ederson de Souza9ab243d2023-08-25 13:58:52 -070047 - 0.1.0 denotes an :ref:`experimental <api_lifecycle_experimental>` API
48 - 0.8.0 denote an :ref:`unstable <api_lifecycle_unstable>` API,
49 - and finally 1.0.0 indicates a :ref:`stable <api_lifecycle_stable>` APIs.
Carles Cufi39930ca2020-02-19 19:03:03 +010050
Ederson de Souza9ab243d2023-08-25 13:58:52 -070051 Changes to APIs in the future will require adapting the version following the
52 guidelines above.
Martí Bolívar2485d762020-10-27 13:09:07 -070053
Martí Bolívar2485d762020-10-27 13:09:07 -070054
Ederson de Souza9ab243d2023-08-25 13:58:52 -070055.. api-overview-table::