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

[Hemant Agrawal <hemant.agrawal@nxp.com>]

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? 
2. Even if they are supported across releases, there is no guarantee that they are not broken.

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

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