On 15/10/2019 16:11, David Marchand wrote:
[SNIP]
>>
>> Signed-off-by: Ray Kinsella <m...@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]
