From patchwork Wed Aug 12 11:26:02 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ray Kinsella X-Patchwork-Id: 75461 Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 79B19A04C2; Wed, 12 Aug 2020 13:26:18 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 101441C13A; Wed, 12 Aug 2020 13:26:18 +0200 (CEST) Received: from dal1relay112.mxroute.com (dal1relay112.mxroute.com [199.181.239.112]) by dpdk.org (Postfix) with ESMTP id 279811C11A for ; Wed, 12 Aug 2020 13:26:17 +0200 (CEST) Received: from filter004.mxroute.com ([149.28.56.236] 149.28.56.236.vultr.com) (Authenticated sender: mN4UYu2MZsgR) by dal1relay112.mxroute.com (ZoneMTA) with ESMTPSA id 173e26ba2da000825f.002 for (version=TLSv1/SSLv3 cipher=ECDHE-RSA-AES128-GCM-SHA256); Wed, 12 Aug 2020 11:26:11 +0000 X-Zone-Loop: e2f5f6fd6d94f387282abb59d0289208b8a66e5b7571 X-Originating-IP: [149.28.56.236] Received: from echo.mxrouting.net (echo.mxrouting.net [116.202.222.109]) by filter004.mxroute.com (Postfix) with ESMTPS id 6CD613E9D4; Wed, 12 Aug 2020 11:26:10 +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=CzM5pnkCEGOWjnIElCk1HGT0M7fbjjZBHzYekJdtEOU=; b=m/65ReKMG/k25mk/+PV2oG7gIU orBc2XLazG6wUCaEsSltPvCjGRjm1H8zmJc4s/B4Rva5IpldAeB3eTtFEnsmEd84GlSsifHfCXPRf kAwOIkvnhvwk72erm4gNVKwwh6EBEakJ5EiJSBiCXhu8E+iAb/MQMR27E43JaLXxUNkbUWWEW7Yxv g0E4kulSKylGmV6ffjyjNWOPQyHvlMf071NkZEYfo+MgBZGScadqmBI7OXVoZVvgQOK6HZnxjykJ8 jrEEAm5Cv3Kxfqh8tXfEq3LHbZemHFlPtZa6iwo2sU5DU225ilpaxwxR/1lFigSvIyjDK7+pWI6Bv RJardhIw==; 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: Wed, 12 Aug 2020 12:26:02 +0100 Message-Id: <1597231565-5094-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 v4] 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 at the head of the abi policy describing the abi stability process that has taken place over the previous year. Signed-off-by: Ray Kinsella --- V4: Few minor changes proposed by Thomas Monjalon. V3: Added the patch version. V2: Updated to add removing aliases to experimental. --- doc/guides/contributing/abi_policy.rst | 37 +++++++++++++++++++++++------- doc/guides/contributing/abi_versioning.rst | 6 ++--- 2 files changed, 32 insertions(+), 11 deletions(-) -- 2.7.4 diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst index ab9daf5..d408439 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,6 +282,33 @@ 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 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