From: Neil Horman <nhorman@tuxdriver.com>
To: Ray Kinsella <mdr@ashroe.eu>
Cc: dev@dpdk.org, thomas@monjalon.net, stephen@networkplumber.org,
bruce.richardson@intel.com, ferruh.yigit@intel.com,
konstantin.ananyev@intel.com, jerinj@marvell.com,
olivier.matz@6wind.com, maxime.coquelin@redhat.com,
john.mcnamara@intel.com, marko.kovacevic@intel.com,
hemant.agrawal@nxp.com, ktraynor@redhat.com
Subject: Re: [dpdk-dev] [PATCH v4 1/4] doc: separate versioning.rst into version and policy
Date: Wed, 25 Sep 2019 10:34:56 -0400 [thread overview]
Message-ID: <20190925143456.GC31002@hmswarspite.think-freely.org> (raw)
In-Reply-To: <e3091934-bd3d-69b5-757d-7d64277f6cd0@ashroe.eu>
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 <mdr@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!
next prev parent reply other threads:[~2019-09-25 14:35 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-09-25 10:23 [dpdk-dev] [PATCH v4 0/4] doc: changes to abi policy introducing major abi versions Ray Kinsella
2019-09-25 10:23 ` [dpdk-dev] [PATCH v4 1/4] doc: separate versioning.rst into version and policy Ray Kinsella
2019-09-25 12:24 ` Neil Horman
2019-09-25 13:01 ` Ray Kinsella
2019-09-25 14:34 ` Neil Horman [this message]
2019-09-27 15:22 ` Ray Kinsella
2019-09-27 15:43 ` Aaron Conole
2019-09-27 16:43 ` Ray Kinsella
2019-09-25 10:23 ` [dpdk-dev] [PATCH v4 2/4] doc: changes to abi policy introducing major abi versions Ray Kinsella
2019-09-25 10:23 ` [dpdk-dev] [PATCH v4 3/4] doc: updates to versioning guide for " Ray Kinsella
2019-09-25 10:23 ` [dpdk-dev] [PATCH v4 4/4] doc: add maintainer for abi policy Ray Kinsella
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190925143456.GC31002@hmswarspite.think-freely.org \
--to=nhorman@tuxdriver.com \
--cc=bruce.richardson@intel.com \
--cc=dev@dpdk.org \
--cc=ferruh.yigit@intel.com \
--cc=hemant.agrawal@nxp.com \
--cc=jerinj@marvell.com \
--cc=john.mcnamara@intel.com \
--cc=konstantin.ananyev@intel.com \
--cc=ktraynor@redhat.com \
--cc=marko.kovacevic@intel.com \
--cc=maxime.coquelin@redhat.com \
--cc=mdr@ashroe.eu \
--cc=olivier.matz@6wind.com \
--cc=stephen@networkplumber.org \
--cc=thomas@monjalon.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).