From 54f019c0afc4db582e86fc5d0476fbefa220a91d Mon Sep 17 00:00:00 2001 From: Irit Date: Fri, 15 May 2020 12:31:37 +0100 Subject: [PATCH 1/5] First stab at API life cycle --- .../guidelines/design_guidelines.md | 16 ++++++++++++++++ docs/introduction/release_process.md | 10 ++++++++++ docs/program-setup/build_rules.md | 17 +++++++++++++++++ 3 files changed, 43 insertions(+) diff --git a/docs/contributing/guidelines/design_guidelines.md b/docs/contributing/guidelines/design_guidelines.md index 31733075c5..74ce64e05f 100644 --- a/docs/contributing/guidelines/design_guidelines.md +++ b/docs/contributing/guidelines/design_guidelines.md @@ -130,6 +130,22 @@ A general module can be split into two APIs, the frontend (or user API) and the - If a callback is called in interrupt context, the API responsible should be clearly documented with a warning. Use a consistent form across all APIs: **"warning: called from interrupt context"** +### Experimental APIs + +All new APIs are considered experimental APIs and identified with `FEATURE_EXPERIMENTAL_API`: + +- For simple APIs (only one source file, or one source file and one header file), or when adding an experimental API to a stable library, use the flag as a preprocessor `ifdef` in the source file: + + ``` + #ifdef FEATURE_EXPERIMENTAL_API + // Code + #endif + ``` + +- For full subsystems or libraries, place them under the directory `FEATURE_EXPERIMENTAL_API`. + +The build system only compiles files under this directory, or using this IFDEF, if the user includes them in the application's configuration. + ## Documentation - Document all entities in a `.h` file using doxygen comment blocks. diff --git a/docs/introduction/release_process.md b/docs/introduction/release_process.md index 49f0f5ee79..9bda7264f1 100644 --- a/docs/introduction/release_process.md +++ b/docs/introduction/release_process.md @@ -47,3 +47,13 @@ Two weeks before each feature release, we implement a code freeze on the master For patch releases, code freeze occurs the Thursday before the release. Patch releases also go through exporter tests and nightly CI tests. After all tests return no errors, we release the latest updates. You can find the most recent release in the `mbed-os` repository with the `latest` tag. A release note accompanies each release. The release notes for major and feature releases are longer and give an overview of the new features. The release notes for the patch releases include only a list of changes and known issues, if applicable. You can find our release notes on [the releases page](https://os.mbed.com/releases/) and on [the blog](https://os.mbed.com/blog/). + +## The API life cycle + +Mbed OS API are managed in three phases: + +1. Experimental: No changes are considered breaking, so they can be changed in any release type. They are on the Mbed OS Master branch and can be included in any Mbed OS build, but are identified as experimental and users have to explicitly include them. +1. Stable: Can only be changed in a non-breaking manner. These are included by default in the Mbed OS full profile and, where appropriate, the bare metal profile. +1. Deprecated: API deprecation is a breaking change, and done only in major releases. + +APIs moved between the three phases only through pull requests raised against the Master branch. diff --git a/docs/program-setup/build_rules.md b/docs/program-setup/build_rules.md index 21332920e2..a054162ae3 100644 --- a/docs/program-setup/build_rules.md +++ b/docs/program-setup/build_rules.md @@ -27,6 +27,7 @@ Label directories are directories that follow a naming convention: an upper case - `TARGET`, constructed from the configuration value `target.extra_labels` and the name of the targets. - `FEATURE`, constructed from the configuration value `target.features`. +- `FEATURE_EXPERIMENTAL_API`, constructed from the configuration value `target.features`. - `COMPONENT`, controlled from the configuration value `target.components`. - `TOOLCHAIN`, controlled completely by the toolchain used to build. @@ -68,6 +69,22 @@ The feature labeled directories are used for software that implements functional In the above example, `mbed compile` includes files in directories named `FEATURE_BLE`, and not directories such as `FEATURE_STORAGE` or `FEATURE_CRYTOCELL310`. +### Experimental directories + +By default, Mbed OS doesn't compile [experimental APIs](). You can override this behaviour by explicitly including "EXPERIMENTAL_API" in `mbed_app.json`: + +``` +{ + “target_overrides” : { + “*” : { + “target.features_add” : [“EXPERIMENTAL_API”] + } + } +} + +``` + + ### Component directories The component labeled directories are used for software that implements funtionality. They are within label directories primarily because we don't expect every program to use this software, and including this software in every build would needlessly increase build time. The configuration value `target.components` entirely controls the set of directories the `COMPONENT` label type includes. The following is a shortened version of an example `targets.json`: From a9210896bc09724560bb97316c8f1c969e49f80f Mon Sep 17 00:00:00 2001 From: Irit Arkin Date: Wed, 10 Jun 2020 11:31:51 +0100 Subject: [PATCH 2/5] Update docs/introduction/release_process.md --- docs/introduction/release_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/introduction/release_process.md b/docs/introduction/release_process.md index 9bda7264f1..a688bc60e2 100644 --- a/docs/introduction/release_process.md +++ b/docs/introduction/release_process.md @@ -50,7 +50,7 @@ After all tests return no errors, we release the latest updates. You can find th ## The API life cycle -Mbed OS API are managed in three phases: +Mbed OS APIs are managed in three phases: 1. Experimental: No changes are considered breaking, so they can be changed in any release type. They are on the Mbed OS Master branch and can be included in any Mbed OS build, but are identified as experimental and users have to explicitly include them. 1. Stable: Can only be changed in a non-breaking manner. These are included by default in the Mbed OS full profile and, where appropriate, the bare metal profile. From 44a4f1817e90eda131b79a1f0b0800d594251db6 Mon Sep 17 00:00:00 2001 From: Irit Arkin Date: Fri, 12 Jun 2020 09:28:08 +0100 Subject: [PATCH 3/5] Update docs/introduction/release_process.md --- docs/introduction/release_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/introduction/release_process.md b/docs/introduction/release_process.md index a688bc60e2..2bddccb9f3 100644 --- a/docs/introduction/release_process.md +++ b/docs/introduction/release_process.md @@ -54,6 +54,6 @@ Mbed OS APIs are managed in three phases: 1. Experimental: No changes are considered breaking, so they can be changed in any release type. They are on the Mbed OS Master branch and can be included in any Mbed OS build, but are identified as experimental and users have to explicitly include them. 1. Stable: Can only be changed in a non-breaking manner. These are included by default in the Mbed OS full profile and, where appropriate, the bare metal profile. -1. Deprecated: API deprecation is a breaking change, and done only in major releases. +1. Deprecated: An API that will be removed in the next major release. Building with a deprecated API will raise a warning, but will not fail. Arm Mbed will announce an upcoming major release so that you can replace the deprecated API in time. APIs moved between the three phases only through pull requests raised against the Master branch. From 4fe854d85bf0c5e948c5f4390686531381daa0a6 Mon Sep 17 00:00:00 2001 From: Irit Arkin Date: Fri, 12 Jun 2020 09:49:05 +0100 Subject: [PATCH 4/5] Update docs/program-setup/build_rules.md --- docs/program-setup/build_rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/program-setup/build_rules.md b/docs/program-setup/build_rules.md index a054162ae3..c5fdb9efda 100644 --- a/docs/program-setup/build_rules.md +++ b/docs/program-setup/build_rules.md @@ -83,7 +83,7 @@ By default, Mbed OS doesn't compile [experimental APIs](). You can override this } ``` - +The `EXPERIMENTAL_API` flag enables experimental APIs but may not activate individual APIs. Please follow each API's documentation to use it. ### Component directories From 8c5d39ade4ba453ec9d61bbc3672c958496e8be1 Mon Sep 17 00:00:00 2001 From: Irit Arkin Date: Fri, 12 Jun 2020 09:55:18 +0100 Subject: [PATCH 5/5] Not sure why the formatting got weird --- docs/introduction/release_process.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/introduction/release_process.md b/docs/introduction/release_process.md index 2bddccb9f3..4d5119cee9 100644 --- a/docs/introduction/release_process.md +++ b/docs/introduction/release_process.md @@ -52,8 +52,8 @@ After all tests return no errors, we release the latest updates. You can find th Mbed OS APIs are managed in three phases: -1. Experimental: No changes are considered breaking, so they can be changed in any release type. They are on the Mbed OS Master branch and can be included in any Mbed OS build, but are identified as experimental and users have to explicitly include them. -1. Stable: Can only be changed in a non-breaking manner. These are included by default in the Mbed OS full profile and, where appropriate, the bare metal profile. -1. Deprecated: An API that will be removed in the next major release. Building with a deprecated API will raise a warning, but will not fail. Arm Mbed will announce an upcoming major release so that you can replace the deprecated API in time. +1. Experimental: No changes are considered breaking, so they can be changed in any release type. They are on the Mbed OS Master branch and can be included in any Mbed OS build, but are identified as experimental and users have to explicitly include them. +1. Stable: Can only be changed in a non-breaking manner. These are included by default in the Mbed OS full profile and, where appropriate, the bare metal profile. +1. Deprecated: An API that will be removed in the next major release. Building with a deprecated API will raise a warning, but will not fail. Arm Mbed will announce an upcoming major release so that you can replace the deprecated API in time. APIs moved between the three phases only through pull requests raised against the Master branch.