Overview

Back in October 2019 we announced the plan to change the Mbed OS release process and the monthly release cadence has now been running since the beginning of this year. This is just one of the changes being implemented on the run up to the next version of Mbed OS.

A lot of work is currently ongoing to remove deprecated APIs from Mbed OS 6 and to ensure that Mbed OS can provide a stable environment for production devices and, to ensure stability can be maintained, a modification to the API Life Cycle is being introduced.

The need to add a mechanism to introduce experimental APIs was proposed to the mbed partner governance forum along with a proposed solution and the forum granted its approval.

Current API policy

The current model to introduce new public APIs involves the initial “pre-production” development of new functionality which introduces new APIs in feature branches. Once considered to be mature enough, the feature branches with the new APIs are introduced to Mbed OS as PRs raised to master according to Mbed OS contribution guidelines. By default, when new APIs land on master they are considered to be “production quality”. Once APIs are merged to master, these APIs should not change as there is a direct impact to users of Mbed and any changes to APIs are only allowed in major releases. APIs are retired by marking them as deprecated and are eventually removed in major releases.

Issues with the current API Policy

The current API policy has served well but it is restricted to two API life cycle phases - mature and deprecated. The consequences of only two API life cycle phases has resulted in APIs being introduced from feature branches prematurely.

As a consequence of moving APIs prematurely to the mature phase, the official API policy has been broken and breaking changes introduced in feature releases. This has been seen as a lack of strict control regarding breaking changes. In addition, there has been a lack of clarity around the public APIs along with a lack of mechanisms to detect changes to public APIs due to public API test coverage not being mandated and example applications and snippets not all running in CI.

The new API Policy being introduced

To remove ambiguity around the maturity of APIs, an additional API phase (experimental) is being added to extend the API lifecycle policy to three phases - Experimental, Stable and Deprecated. This involves the introduction of the FEATURE_EXPERIMENTAL_API flag to identify the experimental APIs in Mbed OS repository.

In addition to the policy change we will improve the definition of breaking changes and continue the work to more clearly identify the public APIs and to improve test coverage. The work was started in Mbed OS 5.14 and will continue in future releases. There will also be significant steps to automate the testing of all the official examples and documentation code snippets.

The future is stable

This new API Life Cycle policy and the introduction of experimental APIs will become visible in the coming months as Mbed OS 6 reaches maturity. These are just some of the changes being introduced to improve the stability of Mbed OS. Others are in the works and will be posted in the coming weeks as the next version of Mbed OS progresses - stay tuned.