On Wed, Sep 25, 2019 at 02:01:01PM +0100, Ray Kinsella wrote:
> Hi Neil,
>
> Thanks for the feedback, other comment below.
>
> On 25/09/2019 13:24, Neil Horman wrote:
> > On Wed, Sep 25, 2019 at 11:23:53AM +0100, Ray Kinsella wrote:
> >> Separate versioning.rst into abi versioning and abi policy guidance, in
> >> preparation for adding more detail to the abi policy.
> >>
> >> Signed-off-by: Ray Kinsella <m...@ashroe.eu>
> >> ---
> >> doc/guides/contributing/abi_policy.rst | 169 +++++++++
> >> doc/guides/contributing/abi_versioning.rst | 427 +++++++++++++++++++++
> >> doc/guides/contributing/index.rst | 3 +-
> >> doc/guides/contributing/versioning.rst | 591
> >> -----------------------------
> >> 4 files changed, 598 insertions(+), 592 deletions(-)
> >> create mode 100644 doc/guides/contributing/abi_policy.rst
> >> create mode 100644 doc/guides/contributing/abi_versioning.rst
> >> delete mode 100644 doc/guides/contributing/versioning.rst
> >>
> >> diff --git a/doc/guides/contributing/abi_policy.rst
> >> b/doc/guides/contributing/abi_policy.rst
> >> new file mode 100644
> >> index 0000000..55bacb4
> >> --- /dev/null
> >> +++ b/doc/guides/contributing/abi_policy.rst
> >> @@ -0,0 +1,169 @@
> >> +.. SPDX-License-Identifier: BSD-3-Clause
> >> + Copyright 2018 The DPDK contributors
> >> +
> >> +.. abi_api_policy:
> >> +
> >> +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.
> >> +
> >> +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.
> >> +
> > This seems..confusing.
>
> Agreed, this is from the original policy. I updated all the references
> to DPDK 2.0 in the abi_versioning document. Clearly missed these ones,
> thanks for that, the text is confusing I will update it.
>
Thank you!
