API change procedure

Introduction

Starting from 3.0 release, nrfx API can no longer be considered as stable for minor version updates. Taking into account the potential impact on the end users, APIs are changed in a few stages.

Rationale

Due to quickly evolving hardware provided by Nordic and requests coming from projects incorporating nrfx, keeping the API stable for minor version releases is very limiting in terms of code flexibility. To address that issue and minimize the impact on the end user, the following procedure was created. As a result, user's code can be more smoothly adapted to a new functionality, without compromising flexibility of the nrfx API.

Scope

The API change procedure may affect drivers' existing functions, structures and types. HAL functions are considered low-level (hence its name) so they can change without notice. We encourage using driver-level APIs where abstractions can mitigate such changes.

Configuration

If you want to use a specific nrfx API version containing a particular set of functionalities, set relevant values of the following configuration symbols corresponding to a standard version numbering:

• NRFX_CONFIG_API_VER_MAJOR

• NRFX_CONFIG_API_VER_MINOR

• NRFX_CONFIG_API_VER_MICRO

You can set them in nrfx_config_common.h file. Otherwise, one of the following default versions will be used:

• The latest nrfx version, if its release involved a major version update.

• The latest nrfx version with a minor version specified in two releases ago, if its release involved only a minor version update.

As a result, if a specific version is not configured, the change will become visible after two subsequent releases.

The nrfx library uses the NRFX_API_VER_AT_LEAST macro and specified nrfx API version internally to use the code variant indicated by the chosen nrfx API version.

Procedure

The API change procedure consists of four stages.

Stage 1: new API introduction

• A new API is added and wrapped in the #if NRFX_API_VER_AT_LEAST(x, y, z) - #endif statement.

• A new API variant is chosen by default or by updating the nrfx API configuration symbols.

• An old API is marked as deprecated in Doxygen documentation and the changelog.

• Corresponding migration notes are provided.

The old API is still in use. The user’s code is not affected if an API version was not set manually.

Stage 2: old API soft deprecation

The old API is still in use. However, it is decorated with macro indicating that the function is deprecated. This results in compiler warnings if this function is still in use.

If the user did not update their code to the new variant, warnings will appear during compilation.

Stage 3: old API hard deprecation

Now the new API is used by default but user can switch back to old API if the previous API version has been chosen.

If the user did not update their code to the new variant, errors will appear during compilation.

Stage 4: old API removal

The old API is permanently removed, hence the user can no longer switch back to it.