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 93E40A04C2; Wed, 12 Aug 2020 12:40:26 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id E8CC91C12C; Wed, 12 Aug 2020 12:40:25 +0200 (CEST) Received: from new4-smtp.messagingengine.com (new4-smtp.messagingengine.com [66.111.4.230]) by dpdk.org (Postfix) with ESMTP id 1DE381C11C for ; Wed, 12 Aug 2020 12:40:24 +0200 (CEST) Received: from compute7.internal (compute7.nyi.internal [10.202.2.47]) by mailnew.nyi.internal (Postfix) with ESMTP id B79C85803D5; Wed, 12 Aug 2020 06:40:23 -0400 (EDT) Received: from mailfrontend2 ([10.202.2.163]) by compute7.internal (MEProxy); Wed, 12 Aug 2020 06:40:23 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=monjalon.net; h= from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding:content-type; s=fm1; bh= J1L5PaKJazSxTuPQM38Tqch6528hCkyNUxvzl8Ad2ic=; b=wTUhE2Bc9iBrDu4B zEL6Ac7a61VvrvMhxRh7wbduRxU1mYREnAt5TugnLoI5MhuyI+T/BpDp6ZtPrguD ASqdU2DmtWRt7DF6XROeieytFu5SGRvEWHNHAoMdv5P8kp6KGecg/D9gRqNeQssu gQzzK3litZdZEiIu3oJ8+z5uyWc5wB5UgFUVSFKv/Wad09EVBC0R5MT68fKhqWCK 0Jk2snQ4uwLVif/0kladErhYfPq04+zRldGMzw7zSwy3V2t6vYynDT/1SyeX0zCd t88VPZtVPZaTo4d7fMkFSnGrNzHDJSxUURAiEvkB3z4HCFecvwp9eFEoo6yxd69c NlEUow== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:content-type :date:from:in-reply-to:message-id:mime-version:references :subject:to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender :x-sasl-enc; s=fm3; bh=J1L5PaKJazSxTuPQM38Tqch6528hCkyNUxvzl8Ad2 ic=; b=QlZsZCFcnXD7+uyv6DBmLQN3wjMMrlsR4/nElURuld+NhvDjQ6WiKLW2R 2xv+6GffgjYyFojRi9S+SeoFlTET40Ooh9KB9M791sB+iaJ1T6OZhn1RYMNRBJvD 6abh5U3RxFo8zm54eIDcO//Rz0I8WZ1CwfHFeay7CHuHGJ9Dg5c16/Vok0OjutG0 Yep3MhhxAglqOIGDE9kcx5ONlefqc2rQIbTymHbKdNtdI6EaGDpzG9lMK5eLvChi d6jcul8jARMjNsntHPgyvQd7jvvjmlcjnSiuCxqvhUn7mgpWiAPHTQuHLoDeEqZg 156UkohB2vd3yXIhp2Rd/qYVzJIDw== X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduiedrledvgdefudcutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenuc fjughrpefhvffufffkjghfggfgtgesthfuredttddtvdenucfhrhhomhepvfhhohhmrghs ucfoohhnjhgrlhhonhcuoehthhhomhgrshesmhhonhhjrghlohhnrdhnvghtqeenucggtf frrghtthgvrhhnpedugefgvdefudfftdefgeelgffhueekgfffhfeujedtteeutdejueei iedvffegheenucfkphepleefrdeirddugeelrdduudegnecuvehluhhsthgvrhfuihiivg eptdenucfrrghrrghmpehmrghilhhfrhhomhepthhhohhmrghssehmohhnjhgrlhhonhdr nhgvth X-ME-Proxy: Received: from xps.localnet (114.149.6.93.rev.sfr.net [93.6.149.114]) by mail.messagingengine.com (Postfix) with ESMTPA id 277BF30600A3; Wed, 12 Aug 2020 06:40:21 -0400 (EDT) From: Thomas Monjalon To: Ray Kinsella Cc: dev@dpdk.org, ferruh.yigit@intel.com, david.marchand@redhat.com, kevin.laatz@intel.com, bruce.richardson@intel.com, hemant.agrawal@nxp.com, Honnappa.Nagarahalli@arm.com, Neil Horman , John McNamara , Marko Kovacevic Date: Wed, 12 Aug 2020 12:40:19 +0200 Message-ID: <9342681.kHEo2Z4vZq@thomas> In-Reply-To: <1597163999-4002-1-git-send-email-mdr@ashroe.eu> References: <1597158977-3667-1-git-send-email-mdr@ashroe.eu> <1597163999-4002-1-git-send-email-mdr@ashroe.eu> MIME-Version: 1.0 Content-Transfer-Encoding: 7Bit Content-Type: text/plain; charset="us-ascii" Subject: Re: [dpdk-dev] [PATCH v3] 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" In the title and below, s/abi/ABI/ 11/08/2020 18:39, Ray Kinsella: > 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 s/a/at/ > abi stability process that has taken place over the previous year. > > Signed-off-by: Ray Kinsella [...] > #. 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. Good idea adding a link here. [...] > - 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>`. OK removing past year considerations. [...] > + > +.. _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. The ending dot must be removed. > + :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 `. Why adding this sentence here? > + > 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); Why updating the version here? A lot of examples are given with v20. > -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.