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

[David Marchand <david.marchand@redhat.com>]

Hello,

On Fri, Sep 27, 2019 at 6:55 PM Ray Kinsella <mdr@ashroe.eu> wrote:
>
> This policy change introduces major ABI versions, these are
> declared every year, typically aligned with the LTS release
> and are supported by subsequent releases in the following year.
> This change is intended to improve ABI stabilty for those projects
> consuming DPDK.

I spotted a few typos (far from being a complete report of them).
We can wait later in the release to fix those, but it would be more
efficient if native speakers proofread those docs.

John and Marko?
Volunteers?

Thanks.


>
> 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?

> +   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?

> +   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?
milestone releases

> +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?


>
> -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?

> +   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]


-- 
David Marchand