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 C05C1A04DC; Tue, 11 Aug 2020 18:36:45 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id CF89D1C01F; Tue, 11 Aug 2020 18:36:44 +0200 (CEST) Received: from dal1relay133.mxroute.com (dal1relay133.mxroute.com [199.181.239.133]) by dpdk.org (Postfix) with ESMTP id 902A51C002 for ; Tue, 11 Aug 2020 18:36:43 +0200 (CEST) Received: from filter003.mxroute.com ([168.235.111.26] 168-235-111-26.cloud.ramnode.com) (Authenticated sender: mN4UYu2MZsgR) by dal1relay133.mxroute.com (ZoneMTA) with ESMTPSA id 173de618208000825f.002 for (version=TLSv1/SSLv3 cipher=ECDHE-RSA-AES128-GCM-SHA256); Tue, 11 Aug 2020 16:36:39 +0000 X-Zone-Loop: bf5dbd80eba87a476489e111202d11b143728209e790 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 C0E8F6003B; Tue, 11 Aug 2020 16:36:37 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=ashroe.eu; s=x; h=References:In-Reply-To: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:List-Id:List-Help:List-Unsubscribe:List-Subscribe: List-Post:List-Owner:List-Archive; bh=kHxa49uC3ijRQQvPZttO6s2jhEaoN5CYBqcSCgdtpIs=; b=WAJxBRBtnwEfJn1WC4jcFc64on Q7dxAZWmnlsVaOck0G/DKuvB82GTH+VKirDcMwoiXIQU9VUT31LYFPZrQhdG/YToAWook4/vq7pxo hd/6ie8yrA5z3AeQecXnhxdZ7BwXA6qOYdUd27UbuxmKs55ZgjOLuQXWRVyGsGtVCW7TN5FWe+/Q1 X77/lNMbagyz27Y5EzpRY2iZoB2BtD3DHqiPHKj7nthmCbNYnDHkWcv8QADZKhn5slmASHOomqKRO j1yBhNsDOTDm64JcygVyq0k2w044FFmMfu2hOSgCu0NPvA8NizFaAkt+mNbWOrTc8VC5zX0buSpLA Kfyk8AVw==; 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 17:36:32 +0100 Message-Id: <1597163794-3907-1-git-send-email-mdr@ashroe.eu> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1597158977-3667-1-git-send-email-mdr@ashroe.eu> References: <1597158977-3667-1-git-send-email-mdr@ashroe.eu> 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 --- V2: Updated to add removing aliases to experimental. --- doc/guides/contributing/abi_policy.rst | 40 ++++++++++++++++++++++++------ doc/guides/contributing/abi_versioning.rst | 6 ++--- 2 files changed, 35 insertions(+), 11 deletions(-) diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst index ab9daf5..31d250a 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,41 @@ 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`. + * Contributors of aliases to experimental in previous releases, as described in + section :ref:`aliasing_experimental_symbols`, are now required to remove + these aliases. + * 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