From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: <dev-bounces@dpdk.org> Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 44594A04A2; Wed, 6 Nov 2019 01:11:30 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id B35B11BFAC; Wed, 6 Nov 2019 01:11:28 +0100 (CET) Received: from new3-smtp.messagingengine.com (new3-smtp.messagingengine.com [66.111.4.229]) by dpdk.org (Postfix) with ESMTP id 33FB11BFAB for <dev@dpdk.org>; Wed, 6 Nov 2019 01:11:27 +0100 (CET) Received: from compute1.internal (compute1.nyi.internal [10.202.2.41]) by mailnew.nyi.internal (Postfix) with ESMTP id 72AE32109; Tue, 5 Nov 2019 19:11:26 -0500 (EST) Received: from mailfrontend1 ([10.202.2.162]) by compute1.internal (MEProxy); Tue, 05 Nov 2019 19:11:26 -0500 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=mesmtp; bh=EKieXKIpTXgRQ/RsK53L4a5vRpY3n09z0UVtu5G8+sM=; b=qFlRcllByw4o MZAbbgqP4BDdIz46gMshGkLLzlbkQ2lRNzt2qA6KnqHNg8KcOH2e8m8Q6zP+D/Kz pcXpoIavTzVOroFKbgANGWEqpphdHSKv4Szb1f1dVYVb0vgwpRai1RG4FTEnvS1b PPACDnHLpMkhH4z7YJkXtjJmbcZduAg= 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=fm1; bh=EKieXKIpTXgRQ/RsK53L4a5vRpY3n09z0UVtu5G8+ sM=; b=u7Sc1R2Gr8qRDFVF89CN6/CyMDZHpCnahHRZRzrH86Rk11R4JvZZP3vFN ZIHRw7O9eu0STgCMIYsX6fuJ2Ip3Fk4n7mhi4yLSk0Vl3diQvE0Qay7cYpu6NLir zTxPx5Rwvj01oGZzP5DCEwx4PxxDXwRwcxmsjorRlnzQfwYHSmIHplgRxc5N2TSV oimLx1apzmIicvp1Sv9i3DB02JNCCqKsUyIr6uJAEJ2Js1y+eMXORQay4lIk4aMs KTeMuCIO1W07I1/09mlox1znu7MkzWlDSynAzW38IF/ELSWl2I6L+iajPY/lpPcO vEGE3zdM6KpngYPVkg/vWbrqi64QQ== X-ME-Sender: <xms:rA_CXWcm3ckfBylothBnFwEq_HcGw5TCtL2DVFsnDj3RygsuSu1ggQ> X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedufedrudduiedgudelucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucenucfjughrpefhvffufffkjghfggfgtgesthfure dttddtvdenucfhrhhomhepvfhhohhmrghsucfoohhnjhgrlhhonhcuoehthhhomhgrshes mhhonhhjrghlohhnrdhnvghtqeenucfkphepleefrddvfedrudelkedrhedunecurfgrrh grmhepmhgrihhlfhhrohhmpehthhhomhgrshesmhhonhhjrghlohhnrdhnvghtnecuvehl uhhsthgvrhfuihiivgeptd X-ME-Proxy: <xmx:rA_CXeBACmEao5sP0SvNBG_bmr18ipzOjYFOJk6t6XSKS7lkrwKPHg> <xmx:rA_CXYZeCbeB4rjlrWpvBZYvjOZ0xuba9uZ4eMZPutmwjLSv_G3brg> <xmx:rA_CXe6pSQgAkVOtvtL-UQ1kpPqygADPeP-iaTXljR4LjAHnFM7lCg> <xmx:rg_CXUR8_BOOOFZhYv4AjhL2p6aIYsQIWR7qKQtZMBx05Hd0i8_JgQ> Received: from xps.localnet (51.198.23.93.rev.sfr.net [93.23.198.51]) by mail.messagingengine.com (Postfix) with ESMTPA id 14C5880063; Tue, 5 Nov 2019 19:11:20 -0500 (EST) From: Thomas Monjalon <thomas@monjalon.net> To: Ray Kinsella <mdr@ashroe.eu> Cc: dev@dpdk.org, stephen@networkplumber.org, bruce.richardson@intel.com, ferruh.yigit@intel.com, konstantin.ananyev@intel.com, jerinj@marvell.com, olivier.matz@6wind.com, nhorman@tuxdriver.com, maxime.coquelin@redhat.com, john.mcnamara@intel.com, marko.kovacevic@intel.com, hemant.agrawal@nxp.com, ktraynor@redhat.com, aconole@redhat.com Date: Wed, 06 Nov 2019 01:11:58 +0100 Message-ID: <1582816.H2LZHI4QzJ@xps> In-Reply-To: <1572967458-16487-3-git-send-email-mdr@ashroe.eu> References: <1572967458-16487-1-git-send-email-mdr@ashroe.eu> <1572967458-16487-3-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 v8 2/4] doc: changes to abi policy introducing major abi versions X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions <dev.dpdk.org> List-Unsubscribe: <https://mails.dpdk.org/options/dev>, <mailto:dev-request@dpdk.org?subject=unsubscribe> List-Archive: <http://mails.dpdk.org/archives/dev/> List-Post: <mailto:dev@dpdk.org> List-Help: <mailto:dev-request@dpdk.org?subject=help> List-Subscribe: <https://mails.dpdk.org/listinfo/dev>, <mailto:dev-request@dpdk.org?subject=subscribe> Errors-To: dev-bounces@dpdk.org Sender: "dev" <dev-bounces@dpdk.org> I'm sorry I still have some comments. But on the positive side, you can see that I carefuly read this doc. 05/11/2019 16:24, Ray Kinsella: > +#. Major ABI versions are declared every **year** and are then supported for one > + year, typically aligned with the :ref:`LTS release <stable_lts_releases>`. As discussed earlier, a major ABI version can be declared less often than one year in the future. An ABI is supported more than one year, because of the LTS branches. That's why I propose to replace with this sentence: " Major ABI versions are declared regularly and are then supported for at least one year, typically aligned with the :ref:`LTS release <stable_lts_releases>`. " > +#. The ABI version is managed at a project level in DPDK, with the ABI version > + reflected in all library's soname. Yes, even the experimental libraries should have the same version, with the minor number incremented at each release. (just a comment to change a policy at the end of this patch) > + 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. Great, the schedule is clear here. > +A major ABI version is declared every year, aligned with that year's LTS > +release, e.g. v19.11. This ABI version is then supported for one year by all > +subsequent releases within that time period, until the next LTS release, e.g. > +v20.11. Let's reword like this: " A new major ABI version can be declared when a new LTS branch is started, e.g. ABI 19 for DPDK 19.11.0. This major ABI version is then supported until the next one, e.g. ABI 20 for DPDK 20.11.0. All ABI changes must be detailed in the release notes. " > +At the declaration of a major ABI version, major version numbers encoded in > +libraries' sonames are bumped to indicate the new version, with the minor > +version reset to ``0``. An example would be ``librte_eal.so.20.3`` would become > +``librte_eal.so.21.0``. > > +Minor versions are incremented to indicate the release of a new ABI compatible > +DPDK release, typically the DPDK quarterly releases. An example of this, might > +be that ``librte_eal.so.20.1`` would indicate the first ABI compatible DPDK > +release, following the declaration of the new major ABI version ``20``. > > +An ABI version is supported in all new releases until the next major ABI version > +is declared. This sentence is repetitive. > When changing the major ABI version, the release notes will detail > +all ABI changes. I suggest to move and reword this sentence above (as in my above reword). > + ABI breakages due to changes such as reorganizing public > + structure fields for aesthetic or readability purposes should be avoided. Why it should be avoided? If the ABI is broken anyway, I don't see any reason to not break it more. > +#. ABI breaking changes (including an alternative map file) can be included with > + deprecation notice, in wrapped way by the ``RTE_NEXT_ABI`` option, to provide > + more details about oncoming changes. ``RTE_NEXT_ABI`` wrapper will be removed > + at the declaration of the next major ABI version. I missed that in discussions. I thought we wanted to wait for the next major ABI. If we allow NEXT_ABI ifdef, we will have 2 DPDK versions (stable and next ABI) to test. > +Libraries marked as ``experimental`` are entirely not considered part of an ABI > +version, and may change without warning at any time. Experimental libraries > +always have a major version of ``0`` to indicate they exist outside of > +ABI Versioning, with the minor version incremented with each ABI change > +to library. It means not all libraries will have the same ABI version. It is contrary of "ABI version is managed at a project level", and I don't see a real benefit of a different version number. Anyway, some experimental functions can live inside a library with a stable ABI version number.