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 ECFCAA04DA; Tue, 11 Aug 2020 17:16:33 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 0888A1C021; Tue, 11 Aug 2020 17:16:33 +0200 (CEST) Received: from qrelay51.mxroute.com (qrelay51.mxroute.com [172.82.139.51]) by dpdk.org (Postfix) with ESMTP id A62481C01F for ; Tue, 11 Aug 2020 17:16:31 +0200 (CEST) Received: from filter003.mxroute.com ([168.235.111.26] 168-235-111-26.cloud.ramnode.com) (Authenticated sender: mN4UYu2MZsgR) by qrelay51.mxroute.com (ZoneMTA) with ESMTPA id 173de181302000be4f.002 for ; Tue, 11 Aug 2020 15:16:26 +0000 X-Zone-Loop: b8d1eee45c968095ac81530ad83dc3eff9c9899ee27a X-Originating-IP: [168.235.111.26] Received: from echo.mxrouting.net (echo.mxrouting.net [116.202.222.109]) by filter003.mxroute.com (Postfix) with ESMTPS id 933366000D; Tue, 11 Aug 2020 15:16:25 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=ashroe.eu; s=x; h=Message-Id:Date:Subject:Cc:To:From:Sender:Reply-To:MIME-Version: Content-Type:Content-Transfer-Encoding:Content-ID:Content-Description: Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID: In-Reply-To:References:List-Id:List-Help:List-Unsubscribe:List-Subscribe: List-Post:List-Owner:List-Archive; bh=z+xQZ8bdrizxFpbQdU4YDg70/SI/NKBIJW3f2/MkOp8=; b=jwrapgL3vLQaXBTFMNXte/jUzb GbCHoEyRBsb71eJMCmT7PJVTqfFr7SK0inurR1djRDWzTMpcsHaaFGC9zUzcYKW3tNbg+HX5kFJxq ow9Jmkf1XMVPNhwZdKNtzZQfPiUCICjON7i4Ip2wRVEHJrzvCjdHEUWOdnBTpDfjUInJxB8NrpJnT FDOkkEHz4lheANhB9n+Uf08VE/p2EUKCCKZWfNPzHS+9rieafXB/eVmvRjiIxf0q0JNWHhcYZY3+4 uEF3fMsDL57Wc6H6KPKu4LBKs1Nu2kYs7UwrBNMjtD32FK6HIF4wHa1xTkPj5iaNTjpI3LrCZag6x 9LBLCNTw==; From: Ray Kinsella To: dev@dpdk.org Cc: ferruh.yigit@intel.com, david.marchand@redhat.com, thomas@monjalon.net, kevin.laatz@intel.com, bruce.richardson@intel.com, hemant.agrawal@nxp.com, Honnappa.Nagarahalli@arm.com, Ray Kinsella , Neil Horman , John McNamara , Marko Kovacevic Date: Tue, 11 Aug 2020 16:16:13 +0100 Message-Id: <1597158977-3667-1-git-send-email-mdr@ashroe.eu> X-Mailer: git-send-email 2.7.4 X-AuthUser: mdr@ashroe.eu Subject: [dpdk-dev] [PATCH] doc: add section describing new abi versions 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" Added a section describing new abi versions, this provides pointers to the relevant amended rules that apply during the abi breakage window. Also remove the large note a the head of the abi policy describing the abi stability process that has taken place over the previous year. Signed-off-by: Ray Kinsella --- doc/guides/contributing/abi_policy.rst | 37 +++++++++++++++++++++++------- doc/guides/contributing/abi_versioning.rst | 6 ++--- 2 files changed, 32 insertions(+), 11 deletions(-) diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst index ab9daf5..fae1eb0 100644 --- a/doc/guides/contributing/abi_policy.rst +++ b/doc/guides/contributing/abi_policy.rst @@ -14,8 +14,8 @@ General Guidelines ------------------ #. Major ABI versions are declared no more frequently than yearly. Compatibility - with the major ABI version is mandatory in subsequent releases until a new - major ABI version is declared. + with the major ABI version is mandatory in subsequent releases until a + :ref:`new major ABI version ` is declared. #. Major ABI versions are usually but not always declared aligned with a :ref:`LTS release `. #. The ABI version is managed at a project level in DPDK, and is reflected in @@ -35,12 +35,6 @@ General Guidelines .. note:: - In 2019, the DPDK community stated its intention to move to ABI stable - releases, over a number of release cycles. This change begins with - maintaining ABI stability through one year of DPDK releases starting from - DPDK 19.11. This policy will be reviewed in 2020, with intention of - lengthening the stability period. Additional implementation detail can be - found in the :ref:`release notes <20_02_abi_changes>`. Please note that this policy does not currently apply to the :doc:`Windows build <../windows_gsg/intro>`. @@ -288,11 +282,38 @@ added to the Release Notes: these changes. Binaries using this library built prior to ABI version 21 will require updating and recompilation. + +.. _new_abi_version: + +New ABI versions +------------------ + +A new ABI version may be declared aligned with a given release. The requirement +to preserve compatibility with the previous major ABI version is then dropped +for the duration of this release cycle. This is commonly known as the *ABI +breakage window*, and some amended rules apply during this cycle: + + * The requirement to preserve compatibility with the previous major ABI + version, as described in the section :ref:`abi_changes` does not apply. + * Contributors of compatibility preserving code in previous releases, are now + required to remove this compatibility code, as described in the section + :ref:`abi_changes`. + * Symbol versioning references to the old ABI version are updated to reference + the new ABI version, as described in the section + :ref:`deprecating_entire_abi`. + * Finally, the *ABI breakage window* is *not* permission to circumvent the + other aspects of the procedures to make ABI changes described in + :ref:`abi_changes`, that is, 3 ACKs of the requirement to break the ABI and + the observance of a deprecation notice are still considered mandatory. + .. _experimental_apis: Experimental ------------ +Major ABI versions are usually but not always declared aligned with a +:ref:`LTS release `. + APIs ~~~~ diff --git a/doc/guides/contributing/abi_versioning.rst b/doc/guides/contributing/abi_versioning.rst index b1d09c7..3d35b1a 100644 --- a/doc/guides/contributing/abi_versioning.rst +++ b/doc/guides/contributing/abi_versioning.rst @@ -673,9 +673,9 @@ symbols. -BIND_DEFAULT_SYMBOL(rte_acl_create, _v20, 20); +BIND_DEFAULT_SYMBOL(rte_acl_create, _v21, 21); -Lastly, any VERSION_SYMBOL macros that point to the old version node should be -removed, taking care to keep, where need old code in place to support newer -versions of the symbol. +Lastly, any VERSION_SYMBOL macros that point to the old version nodes should be +removed, taking care to preserve any code that is shared with the new version +node. Running the ABI Validator -- 2.7.4