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 <carles.cufi@nordicsemi.no>

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 <rfcs>` 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: <subsystem>
+      Title:     RFC: Breaking API Change: <subsystem>
       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
+   Breaking API changes will be listed and described in the migration guide.
-   release notes.
 
 Deprecated
 ***********

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 <stable_api_changes>`, the
+Group. For example for :ref:`breaking API changes <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
+The issue or PR describes a breaking change to a stable API. See additional information
-in :ref:`stable_api_changes`.
+in :ref:`breaking_api_changes`.
 
 * *Bug*