Martí Bolívar | 4ba332a | 2020-03-20 11:10:02 -0700 | [diff] [blame] | 1 | .. _api_overview: |
Carles Cufi | 39930ca | 2020-02-19 19:03:03 +0100 | [diff] [blame] | 2 | |
Martí Bolívar | 4ba332a | 2020-03-20 11:10:02 -0700 | [diff] [blame] | 3 | API Overview |
| 4 | ############ |
Carles Cufi | 39930ca | 2020-02-19 19:03:03 +0100 | [diff] [blame] | 5 | |
Martí Bolívar | 4ba332a | 2020-03-20 11:10:02 -0700 | [diff] [blame] | 6 | The table lists Zephyr's APIs and information about them, including their |
Fabio Baltieri | 2875f00 | 2022-10-03 11:26:34 +0000 | [diff] [blame] | 7 | current :ref:`stability level <api_lifecycle>`. More details about API changes |
| 8 | between major releases are available in the :ref:`zephyr_release_notes`. |
Carles Cufi | 39930ca | 2020-02-19 19:03:03 +0100 | [diff] [blame] | 9 | |
Ederson de Souza | 9ab243d | 2023-08-25 13:58:52 -0700 | [diff] [blame] | 10 | The version column uses `semantic version <https://semver.org/>`_, and has the |
| 11 | following expectations: |
Martí Bolívar | 2485d76 | 2020-10-27 13:09:07 -0700 | [diff] [blame] | 12 | |
Ederson de Souza | 9ab243d | 2023-08-25 13:58:52 -0700 | [diff] [blame] | 13 | * 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 Cufi | 39930ca | 2020-02-19 19:03:03 +0100 | [diff] [blame] | 15 | |
Ederson de Souza | 9ab243d | 2023-08-25 13:58:52 -0700 | [diff] [blame] | 16 | * 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 Cufi | 39930ca | 2020-02-19 19:03:03 +0100 | [diff] [blame] | 20 | |
Ederson de Souza | 9ab243d | 2023-08-25 13:58:52 -0700 | [diff] [blame] | 21 | * 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ívar | 2485d76 | 2020-10-27 13:09:07 -0700 | [diff] [blame] | 24 | |
Ederson de Souza | 9ab243d | 2023-08-25 13:58:52 -0700 | [diff] [blame] | 25 | * 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 Cufi | 39930ca | 2020-02-19 19:03:03 +0100 | [diff] [blame] | 28 | |
Ederson de Souza | 9ab243d | 2023-08-25 13:58:52 -0700 | [diff] [blame] | 29 | * 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 Cufi | 39930ca | 2020-02-19 19:03:03 +0100 | [diff] [blame] | 32 | |
Ederson de Souza | 9ab243d | 2023-08-25 13:58:52 -0700 | [diff] [blame] | 33 | * 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 McCrae | 71e7cf8 | 2023-01-15 12:35:24 +0000 | [diff] [blame] | 39 | |
Ederson de Souza | 9ab243d | 2023-08-25 13:58:52 -0700 | [diff] [blame] | 40 | * Major version X (x.Y.z | x > 0) MUST be incremented if a compatibility |
| 41 | breaking change was made to the API. |
Carlo Caione | f5c66e9 | 2023-05-30 17:04:08 +0200 | [diff] [blame] | 42 | |
Ederson de Souza | 9ab243d | 2023-08-25 13:58:52 -0700 | [diff] [blame] | 43 | .. note:: |
| 44 | Version for existing APIs are initially set based on the current state of the |
| 45 | APIs: |
Jamie McCrae | 3205a58 | 2023-09-27 09:37:35 +0100 | [diff] [blame] | 46 | |
Ederson de Souza | 9ab243d | 2023-08-25 13:58:52 -0700 | [diff] [blame] | 47 | - 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 Cufi | 39930ca | 2020-02-19 19:03:03 +0100 | [diff] [blame] | 50 | |
Ederson de Souza | 9ab243d | 2023-08-25 13:58:52 -0700 | [diff] [blame] | 51 | Changes to APIs in the future will require adapting the version following the |
| 52 | guidelines above. |
Martí Bolívar | 2485d76 | 2020-10-27 13:09:07 -0700 | [diff] [blame] | 53 | |
Martí Bolívar | 2485d76 | 2020-10-27 13:09:07 -0700 | [diff] [blame] | 54 | |
Ederson de Souza | 9ab243d | 2023-08-25 13:58:52 -0700 | [diff] [blame] | 55 | .. api-overview-table:: |