From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id ADAE5A0613 for ; Wed, 25 Sep 2019 16:35:20 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 3C4071BEF8; Wed, 25 Sep 2019 16:35:19 +0200 (CEST) Received: from smtp.tuxdriver.com (charlotte.tuxdriver.com [70.61.120.58]) by dpdk.org (Postfix) with ESMTP id 99EA41B079 for ; Wed, 25 Sep 2019 16:35:17 +0200 (CEST) Received: from cpe-2606-a000-111b-43ee-0-0-0-162e.dyn6.twc.com ([2606:a000:111b:43ee::162e] helo=localhost) by smtp.tuxdriver.com with esmtpsa (TLSv1:AES256-SHA:256) (Exim 4.63) (envelope-from ) id 1iD8Nh-0007sq-M9; Wed, 25 Sep 2019 10:35:09 -0400 Date: Wed, 25 Sep 2019 10:34:56 -0400 From: Neil Horman To: Ray Kinsella 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 Message-ID: <20190925143456.GC31002@hmswarspite.think-freely.org> References: <1569407036-1727-1-git-send-email-mdr@ashroe.eu> <1569407036-1727-2-git-send-email-mdr@ashroe.eu> <20190925122417.GB31002@hmswarspite.think-freely.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.12.1 (2019-06-15) X-Spam-Score: -2.9 (--) X-Spam-Status: No Subject: Re: [dpdk-dev] [PATCH v4 1/4] doc: separate versioning.rst into version and policy X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" 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 > >> --- > >> 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!