Re: [dpdk-dev] [PATCH v6 2/4] doc: changes to abi policy introducing major abi versions

[Ray Kinsella <mdr@ashroe.eu>]

On 15/10/2019 16:11, David Marchand wrote:
[SNIP]
>>
>> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
>> ---
>>  doc/guides/contributing/abi_policy.rst             | 321 +++++++++++++++------
>>  .../contributing/img/abi_stability_policy.png      | Bin 0 -> 61277 bytes
>>  doc/guides/contributing/img/what_is_an_abi.png     | Bin 0 -> 151683 bytes
>>  doc/guides/contributing/stable.rst                 |  12 +-
>>  4 files changed, 241 insertions(+), 92 deletions(-)
>>  create mode 100644 doc/guides/contributing/img/abi_stability_policy.png
>>  create mode 100644 doc/guides/contributing/img/what_is_an_abi.png
>>
>> diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
>> index 55bacb4..8862d24 100644
>> --- a/doc/guides/contributing/abi_policy.rst
>> +++ b/doc/guides/contributing/abi_policy.rst
>> @@ -1,33 +1,46 @@
>>  ..  SPDX-License-Identifier: BSD-3-Clause
>> -    Copyright 2018 The DPDK contributors
>> +    Copyright 2019 The DPDK contributors
>>
>> -.. abi_api_policy:
>> +.. _abi_policy:
>>
>> -DPDK ABI/API policy
>> -===================
>> +ABI Policy
>> +==========
>>
>>  Description
>>  -----------
>>
>> -This document details some methods for handling ABI management in the DPDK.
>> +This document details the management policy that ensures the long-term stability
>> +of the DPDK ABI and API.
>>
>>  General Guidelines
>>  ------------------
>>
>> -#. Whenever possible, ABI should be preserved
>> -#. ABI/API may be changed with a deprecation process
>> -#. The modification of symbols can generally be managed with versioning
>> -#. Libraries or APIs marked in ``experimental`` state may change without constraint
>> -#. New APIs will be marked as ``experimental`` for at least one release to allow
>> -   any issues found by users of the new API to be fixed quickly
>> -#. The addition of symbols is generally not problematic
>> -#. The removal of symbols generally is an ABI break and requires bumping of the
>> -   LIBABIVER macro
>> -#. Updates to the minimum hardware requirements, which drop support for hardware which
>> -   was previously supported, should be treated as an ABI change.
>> -
>> -What is an ABI
>> -~~~~~~~~~~~~~~
>> +#. Major ABI versions are declared every **year** and are then supported for one
>> +   year, typically aligned with the :ref:`LTS release <stable_lts_releases>`.
>> +#. The ABI version is managed at a project level in DPDK, with the ABI version
>> +   reflected in all :ref:`library's soname <what_is_soname>`.
>> +#. The ABI should be preserved and not changed lightly. ABI changes must follow
>> +   the outlined :ref:`deprecation process <abi_changes>`.
>> +#. The addition of symbols is generally not problematic. The modification of
>> +   symbols is managed with :ref:`ABI Versioning <abi_versioning>`.
>> +#. The removal of symbols is considered an :ref:`ABI breakage <abi_breakages>`,
>> +   once approved these will form part of the next ABI version.
>> +#. Libraries or APIs marked as :ref:`Experimental <experimental_apis>` are not
>> +   considered part of an ABI version and may change without constraint.
>> +#. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop
>> +   support for hardware which was previously supported, should be treated as an
>> +   ABI change.
>> +
>> +.. note::
>> +
>> +   In 2019, the DPDK community stated it's intention to move to ABI stable
> 
> its?
ACK, done

> 
>> +   releases, over a number of release cycles. Beginning with maintaining ABI
>> +   stability through one year of DPDK releases starting from DPDK 19.11. This
> 
> sentence without a verb?

ACK, done - rewritten to be clearer.
(maintain is a verb BTW).

> 
>> +   policy will be reviewed in 2020, with intention of lengthening the stability
>> +   period.
>> +
>> +What is an ABI?
>> +~~~~~~~~~~~~~~~
>>
>>  An ABI (Application Binary Interface) is the set of runtime interfaces exposed
>>  by a library. It is similar to an API (Application Programming Interface) but
>> @@ -39,30 +52,80 @@ Therefore, in the case of dynamic linking, it is critical that an ABI is
>>  preserved, or (when modified), done in such a way that the application is unable
>>  to behave improperly or in an unexpected fashion.
>>
>> +.. _figure_what_is_an_abi:
>> +
>> +.. figure:: img/what_is_an_abi.*
>> +
>> +*Figure 1. Illustration of DPDK API and ABI .*
>>
>> -ABI/API Deprecation
>> --------------------
>> +
>> +What is an ABI version?
>> +~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +An ABI version is an instance of a library's ABI at a specific release. Certain
>> +releases are considered by the community to be milestone releases, the yearly
>> +LTS for example. Supporting those milestone release's ABI for some number of
>> +subsequent releases is desirable to facilitate application upgrade. Those ABI
>> +version's aligned with milestones release are therefore called 'ABI major
> 
> versions?
ACK, done
> milestone releases
ACK, done

> 
>> +versions' and are supported for some number of releases.
>> +
>> +More details on major ABI version can be found in the :ref:`ABI versioning
>> +<major_abi_versions>` guide.
>>
>>  The DPDK ABI policy
>> -~~~~~~~~~~~~~~~~~~~
>> +-------------------
>> +
>> +A major ABI version is declared every year, aligned with that year's LTS
>> +release, e.g. v19.11. This ABI version is then supported for one year by all
>> +subsequent releases within that time period, until the next LTS release, e.g.
>> +v20.11.
>> +
>> +At the declaration of a major ABI version, major version numbers encoded in
>> +libraries soname's are bumped to indicate the new version, with the minor
>> +version reset to ``0``. An example would be ``librte_eal.so.20.3`` would become
>> +``librte_eal.so.21.0``.
>>
>> -ABI versions are set at the time of major release labeling, and the ABI may
>> -change multiple times, without warning, between the last release label and the
>> -HEAD label of the git tree.
>> +The ABI may then change multiple times, without warning, between the last major
>> +ABI version increment and the HEAD label of the git tree, with the condition
>> +that ABI compatibility with the major ABI version is preserved and therefore
>> +soname's do not change.
>>
>> -ABI versions, once released, are available until such time as their
>> -deprecation has been noted in the Release Notes for at least one major release
>> -cycle. For example consider the case where the ABI for DPDK 2.0 has been
>> -shipped and then a decision is made to modify it during the development of
>> -DPDK 2.1. The decision will be recorded in the Release Notes for the DPDK 2.1
>> -release and the modification will be made available in the DPDK 2.2 release.
>> +Minor versions are incremented to indicate the release of a new ABI compatible
>> +DPDK release, typically the DPDK quarterly releases. An example of this, might
>> +be that ``librte_eal.so.20.1`` would indicate the first ABI compatible DPDK
>> +release, following the declaration of the new major ABI version ``20``.
>>
>> -ABI versions may be deprecated in whole or in part as needed by a given
>> -update.
>> +ABI versions, are supported by each release until such time as the next major
>> +ABI version is declared. At that time, the deprecation of the previous major ABI
>> +version will be noted in the Release Notes with guidance on individual symbol
>> +depreciation and upgrade notes provided.
> 
> deprecation?

Gargh ... 
ACK, done

> 
> 
>>
>> -Some ABI changes may be too significant to reasonably maintain multiple
>> -versions. In those cases ABI's may be updated without backward compatibility
>> -being provided. The requirements for doing so are:
>> +.. _figure_abi_stability_policy:
>> +
>> +.. figure:: img/abi_stability_policy.*
>> +
>> +*Figure 2. Mapping of new ABI versions and ABI version compatibility to DPDK
>> +releases.*
>> +
>> +.. _abi_changes:
>> +
>> +ABI Changes
>> +~~~~~~~~~~~
>> +
>> +The ABI may still change after the declaration of a major ABI version, that is
>> +new APIs may be still added or existing APIs may be modified.
>> +
>> +.. Warning::
>> +
>> +   Note that, this policy details the method by which the ABI may be changed,
>> +   with due regard to preserving compatibility and observing depreciation
> 
> deprecation?

ACK, done

> 
>> +   notices. This process however should not be undertaken lightly, as a general
>> +   rule ABI stability is extremely important for downstream consumers of DPDK.
>> +   The ABI should only be changed for significant reasons, such as performance
>> +   enhancements. ABI breakages due to changes such as reorganizing public
>> +   structure fields for aesthetic or readability purposes should be avoided.
>> +
>> +The requirements for changing the ABI are:
> 
> [snip]