First stab at API life cycle

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.

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 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.
+
+APIs moved between the three phases only through pull requests raised against the Master branch.

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”]
+     }
+  }
+}
+
+```
+<!--so for a specific one, or does this now allow me to use all experimental APIs in one giant go?-->
+
 ### 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`: