From d053b8bf3bc743d42b8b8e4d9119b3e4bb35341b Mon Sep 17 00:00:00 2001 From: Carles Cufi Date: Tue, 19 Dec 2023 16:35:16 +0100 Subject: [PATCH] doc: Rename stable API change to breaking change It is often confusing for users and developers alike to see the sentence "stable API change" in a label or in the release notes. Stable APIs can change in at least two ways (retaining compatibility or not), and so it is preferrable to use a term that clearly describes the change as incompatible, by using the common term "breaking". Signed-off-by: Carles Cufi --- doc/develop/api/api_lifecycle.rst | 23 +++++++++++------------ doc/project/dev_env_and_tools.rst | 8 ++++---- 2 files changed, 15 insertions(+), 16 deletions(-) diff --git a/doc/develop/api/api_lifecycle.rst b/doc/develop/api/api_lifecycle.rst index 8f1f689c12..b34832655c 100644 --- a/doc/develop/api/api_lifecycle.rst +++ b/doc/develop/api/api_lifecycle.rst @@ -94,23 +94,23 @@ In order to declare an API ``stable``, the following steps need to be followed: `Zephyr Architecture meeting`_ where, barring any objections, the Pull Request will be merged -.. _stable_api_changes: +.. _breaking_api_changes: -Introducing incompatible changes +Introducing breaking API changes ================================ -A stable API, as described above strives to remain backwards-compatible through +A stable API, as described above, strives to remain backwards-compatible through its life-cycle. There are however cases where fulfilling this objective prevents -technical progress or is simply unfeasible without unreasonable burden on the +technical progress, or is simply unfeasible without unreasonable burden on the maintenance of the API and its implementation(s). -An incompatible change is defined as one that forces users to modify their +A breaking API change is defined as one that forces users to modify their existing code in order to maintain the current behavior of their application. The need for recompilation of applications (without changing the application -itself) is not considered an incompatible change. +itself) is not considered a breaking API change. In order to restrict and control the introduction of a change that breaks the -promise of backwards compatibility the following steps must be followed whenever +promise of backwards compatibility, the following steps must be followed whenever such a change is considered necessary in order to accept it in the project: #. An :ref:`RFC issue ` must be opened on GitHub with the following @@ -118,7 +118,7 @@ such a change is considered necessary in order to accept it in the project: .. code-block:: none - Title: RFC: API Change: + Title: RFC: Breaking API Change: Contents: - Problem Description: - Background information on why the change is required - Proposed Change (detailed): @@ -133,7 +133,7 @@ such a change is considered necessary in order to accept it in the project: Instead of a written description of the changes, the RFC issue may link to a Pull Request containing those changes in code form. -#. The RFC issue must be labeled with the GitHub ``Stable API Change`` label +#. The RFC issue must be labeled with the GitHub ``Breaking API Change`` label #. The RFC issue must be submitted for discussion in the next `Zephyr Architecture meeting`_ #. An email must be sent to the ``devel`` mailing list with a subject identical @@ -164,7 +164,7 @@ The Pull Request must include the following: the corresponding maintainers - An entry in the "API Changes" section of the release notes for the next upcoming release -- The labels ``API``, ``Stable API Change`` and ``Release Notes``, as well as +- The labels ``API``, ``Breaking API Change`` and ``Release Notes``, as well as any others that are applicable Once the steps above have been completed, the outcome of the proposal will @@ -177,8 +177,7 @@ If the Pull Request is merged then an email must be sent to the ``devel`` and .. note:: - Incompatible changes will be announced in the "API Changes" section of the - release notes. + Breaking API changes will be listed and described in the migration guide. Deprecated *********** diff --git a/doc/project/dev_env_and_tools.rst b/doc/project/dev_env_and_tools.rst index 8269e891d4..3d7e5fd4bb 100644 --- a/doc/project/dev_env_and_tools.rst +++ b/doc/project/dev_env_and_tools.rst @@ -111,7 +111,7 @@ TSC and Working Groups Changes that introduce new features or functionality or change the way the overall system works need to be reviewed by the TSC or the responsible Working -Group. For example for :ref:`stable API changes `, the +Group. For example for :ref:`breaking API changes `, the proposal needs to be presented in the Architecture meeting so that the relevant stakeholders are made aware of the change. @@ -383,10 +383,10 @@ following `TSC meeting`_ if time permits. .. _`TSC meeting`: https://github.com/zephyrproject-rtos/zephyr/wiki/Zephyr-Committee-and-Working-Group-Meetings#technical-steering-committee-tsc -* *Stable API Change* +* *Breaking API Change* -The issue or PR describes a change to a stable API. See additional information -in :ref:`stable_api_changes`. +The issue or PR describes a breaking change to a stable API. See additional information +in :ref:`breaking_api_changes`. * *Bug*