doc/development_process/api_lifecycle.rst

.. _api_lifecycle:

API Lifecycle
#############

Developers using Zephyr's APIs need to know how long they can trust that a
given API will not change in future releases. At the same time, developers
maintaining and extending Zephyr's APIs need to be able to introduce
new APIs that aren't yet fully proven, and to potentially retire old APIs when they're
no longer optimal or supported by the underlying platforms.


.. figure:: api_lifecycle.png
    :align: center
    :alt: API Life Cycle
    :figclass: align-center

    API Life Cycle


Experimental
*************

Experimental APIs denote that a feature was introduced recently, and may change
or be removed in future versions. Try it out and provide feedback
to the community via the `Developer mailing list <https://lists.zephyrproject.org/g/devel>`_.

Peripheral APIs (Hardware Related)
==================================

When introducing an API (public header file with documentation) for a new
peripheral or driver subsystem, review of the API is enforced and is driven by
the API working group consisting of representatives from different vendors.

The following requirements apply to new APIs:

- Documentation of the API (usage)
  explaining its design and assumptions, how it is to be used, current
  implementation limitations, and future potential, if appropriate.
- The API introduction should be accompanied by at least one driver
  implementing this API
- At least one sample using the new API

The API shall be promoted to ``unstable`` when it has at least two
implementations on different hardware platforms.

Hardware Agnostic APIs
=======================

For hardware agnostic APIs, multiple applications are required to promote an
API from ``experimental`` to ``unstable``.


Unstable
********

The API is in the process of settling, but has not yet had sufficient real-world
testing to be considered stable. The API is considered generic in nature and can
be used on different hardware platforms.

.. note::

   Changes will not be announced.

Stable
*******

The API has proven satisfactory, but cleanup in the underlying code may cause
minor changes. Backwards-compatibility will be maintained if reasonable.

An API can be declared ``stable`` after fulfilling the following requirements:

- Test cases for the new API with 100% coverage
- Complete documentation in code. All public interfaces shall be documented
  and available in online documentation.
- The API has been in-use and was available in at least 2 development releases
- Stable APIs can get backward compatible updates, bug fixes and security fixes
  at any time.

.. note::

   Incompatible changes will be announced in the release notes.

Deprecated
***********

.. note::

   Unstable APIs can be removed without deprecation at any time.

The following are the requirements for deprecating an existing API:

- Deprecation Time (stable APIs): 2 Releases
  The API needs to be marked as deprecated in at least two full releases.
  For example, if an API was first deprecated in release 1.14,
  it will be ready to be removed in 1.16 at the earliest.
  There may be special circumstances, determined by the API working group,
  where an API is deprecated sooner.
- What is required when deprecating:

  - Mark as deprecated
  - Document the deprecation
  - All usage in Zephyr for deprecated API needs to be modified
  - Change needs to be atomic and bisectable
  - Code using the deprecated API needs to be modified to remove usage of said
    API

During the deprecation waiting period, the API will be in the ``deprecated``
state. The Zephyr maintainers will track usage of deprecated APIs on
``docs.zephyrproject.org`` and support developers migrating their code. Zephyr
will continue to provide warnings:

- API documentation will inform users that the API is deprecated.
- Attempts to use a deprecated API at build time will log a warning to the
  console.


Retired
*******

In this phase, the API is removed.

The target removal date is 2 releases after deprecation is announced.
The Zephyr maintainers will decide when to actually remove the API: this
will depend on how many developers have successfully migrated from the
deprecated API, and on how urgently the API needs to be removed.

If it's OK to remove the API, it will be removed. The maintainers will remove
the corresponding documentation, and communicate the removal in the usual ways:
the release notes, mailing lists, Github issues and pull-requests.

If it's not OK to remove the API, the maintainers will continue to support
migration and aim to remove the API in the next release.