[dpdk-dev] [PATCH v6 1/4] doc: separate versioning.rst into version and policy

[Ray Kinsella]

Hemant,

Patch 1/4 - doc: separate versioning.rst into version and policy.

So it essentially re-organizes the existing policy into two separate
documents, one dealing with the policy and the other dealing with the
mechanics of abi versioning

Patch 2/4 -  doc: changes to abi policy introducing major abi versions

Actually details the changes to the policy.

Other comments inline below.

Ray K

On 01/10/2019 13:50, Hemant Agrawal wrote:
> Hi Ray,
> 
>> +DPDK ABI/API policy
>> +===================
>> +
>> +Description
>> +-----------
>> +
>> +This document details some methods for handling ABI management in the
>> DPDK.
>> +
>> +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.
> 
> [Hemant] You mean the specific HW pmds? 
> 1. Why dropping HW PMD is a ABI change? 

So this is part of the original policy and you are correct, it isn't
strictly abi - I think the original policy's author, wanted it treated
the same way so that a given ABI version would not drop support for
hardware.

> 2. Even if they are supported across releases, there is no guarantee that they are not broken.

True

> 
>> +
>> +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 is the result of compilation.  It is also effectively
>> +cloned when applications link to dynamic libraries.  That is to say
>> +when an application is compiled to link against dynamic libraries, it
>> +is assumed that the ABI remains constant between the time the application
>> is compiled/linked, and the time that it runs.
>> +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.
>> +
>> +
>> +ABI/API Deprecation
>> +-------------------
>> +
>> +The DPDK ABI policy
>> +~~~~~~~~~~~~~~~~~~~
>> +
>> +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.
>> +
>> +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.
>> +
> [Hemant]  Is it possible to update the DPDK numbering to current versioning, instead of using old 2.x numbering?

Already done, see Patch 2/4

>> +ABI versions may be deprecated in whole or in part as needed by a given
>> +update.
>> +
>> +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:
>> +
>> +#. At least 3 acknowledgments of the need to do so must be made on the
>> +   dpdk.org mailing list.
>> +
>> +   - The acknowledgment of the maintainer of the component is mandatory,
>> or if
>> +     no maintainer is available for the component, the tree/sub-tree
>> maintainer
>> +     for that component must acknowledge the ABI change instead.
>> +
>> +   - It is also recommended that acknowledgments from different "areas of
>> +     interest" be sought for each deprecation, for example: from NIC
>> vendors,
>> +     CPU vendors, end-users, etc.
>> +
>> +#. The changes (including an alternative map file) can be included with
>> +   deprecation notice, in wrapped way by the ``RTE_NEXT_ABI`` option,
>> +   to provide more details about oncoming changes.
>> +   ``RTE_NEXT_ABI`` wrapper will be removed when it become the default
>> ABI.
> 
> [Hemant]  The older implementation will or can be removed at this point of time? 

Detailed in Patch 2/4.

it says ... At the declaration of the next major ABI version, those ABI
changes then become a formal part of the new ABI and the requirement to
preserve ABI compatibility with the last major ABI version is then
dropped ...

Thanks,

Ray K