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 264AFA04A2; Wed, 6 Nov 2019 09:52:46 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 55E281C02D; Wed, 6 Nov 2019 09:52:45 +0100 (CET) Received: from q2relay232.mxroute.com (q2relay232.mxroute.com [160.202.107.232]) by dpdk.org (Postfix) with ESMTP id D96A41C010 for ; Wed, 6 Nov 2019 09:52:43 +0100 (CET) Received: from filter003.mxroute.com [168.235.111.26] (Authenticated sender: mN4UYu2MZsgR) by q2relay232.mxroute.com (ZoneMTA) with ESMTPSA id 16e3fea7bb9000f36a.002 for (version=TLSv1/SSLv3 cipher=ECDHE-RSA-AES128-GCM-SHA256); Wed, 06 Nov 2019 08:52:42 +0000 X-Zone-Loop: d6cb0e58ed3e8d27041651ee7bf137acca47964943e4 X-Originating-IP: [168.235.111.26] Received: from galaxy.mxroute.com (unknown [23.92.70.113]) by filter003.mxroute.com (Postfix) with ESMTPS id 840D96115B; Wed, 6 Nov 2019 08:52:35 +0000 (UTC) Received: from irdmzpr02-ext.ir.intel.com ([192.198.151.37]) by galaxy.mxroute.com with esmtpsa (TLSv1.2:ECDHE-RSA-AES128-GCM-SHA256:128) (Exim 4.91) (envelope-from ) id 1iSGr9-0004nj-7T; Wed, 06 Nov 2019 03:40:02 -0500 To: Thomas Monjalon 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 References: <1572967458-16487-1-git-send-email-mdr@ashroe.eu> <1572967458-16487-3-git-send-email-mdr@ashroe.eu> <1582816.H2LZHI4QzJ@xps> From: Ray Kinsella Openpgp: preference=signencrypt Autocrypt: addr=mdr@ashroe.eu; keydata= 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 Message-ID: Date: Wed, 6 Nov 2019 08:49:32 +0000 User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:60.0) Gecko/20100101 Thunderbird/60.9.0 MIME-Version: 1.0 In-Reply-To: <1582816.H2LZHI4QzJ@xps> Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 8bit X-AuthUser: mdr@ashroe.eu 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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" On 06/11/2019 00:11, Thomas Monjalon wrote: > I'm sorry I still have some comments. > But on the positive side, you can see that I carefuly read this doc. no worries. > > 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 `. > > 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 `. > " So look, this one was a decision of the technical board. My position is still what was agreed was, "declared every year, and supported for one year". I like it, it's crystal clear what is the policy, until we change the policy. That said, I can make the change no problem, but I need some others to chime in to ok it. Perhaps at the head of the Techboard today? > >> +#. 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) It's described elsewhere in the document, experimental libraries have a major ABI version of 0, to indicate they exist outside of ABI management. Minor number then changes as the experimental library changes as before. > >> + 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. > " This is more ambiguous, although what I said above stands. If there is general agreement with changing this part of the policy, I am ok to make the change. > >> +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. ACK >> 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). ACK > >> + 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. This is text from the original ABI Policy - I think the general sentiment still stands. Just because you have an ABI Breakage window doesn't mean you should feel free to break the ABI. The 3 ACKs required from Technical Board member to change the ABI, are another reflection of this. As a general rule. Unnecessary changes should still be avoided, to reduce ABI churn between ABI versions. >> +#. 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. This is text from the original ABI Policy - the purpose remains the same. If you add an ABI breaking change in say 20.02, that clearly can't see the light of day until 20.11 You may still opt to prepare the community for the change, by putting your code out wrapped in a NEXT_ABI and flagging it. You then get the option for people, so inclined, to build and try your code. I can't see it being used often, but it is another tool in the box of managing ABI change. > >> +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. There is a benefit, major version 0 is a very clear indication that the library exists outside of ABI management. A library isn't in the ABI, until it is in the ABI - an then it gets added to the major version number. > Anyway, some experimental functions can live inside a library > with a stable ABI version number True, but if an entire library is experimental - let's be crystal clear about that.