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 CD139A32A3 for ; Fri, 25 Oct 2019 14:46:02 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 6F17B1C195; Fri, 25 Oct 2019 14:46:01 +0200 (CEST) Received: from qrelay150.mxroute.com (qrelay150.mxroute.com [172.82.139.150]) by dpdk.org (Postfix) with ESMTP id 57DA11C133 for ; Fri, 25 Oct 2019 14:46:00 +0200 (CEST) Received: from filter004.mxroute.com (unknown [94.130.183.33]) (using TLSv1.2 with cipher ADH-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by qrelay150.mxroute.com (Postfix) with ESMTPS id 79F3714094A; Fri, 25 Oct 2019 08:45:59 -0400 (EDT) Received: from galaxy.mxroute.com (unknown [23.92.70.113]) by filter004.mxroute.com (Postfix) with ESMTPS id 8DC333E9F9; Fri, 25 Oct 2019 12:45:56 +0000 (UTC) Received: from [192.198.151.44] by galaxy.mxroute.com with esmtpsa (TLSv1.2:ECDHE-RSA-AES128-GCM-SHA256:128) (Exim 4.91) (envelope-from ) id 1iNynN-0005LV-Ct; Fri, 25 Oct 2019 08:34:21 -0400 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: <1569603283-1857-1-git-send-email-mdr@ashroe.eu> <1569603283-1857-3-git-send-email-mdr@ashroe.eu> <10410603.iXVFKWJQZn@xps> From: Ray Kinsella Openpgp: preference=signencrypt Autocrypt: addr=mdr@ashroe.eu; keydata= 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 Message-ID: <37defad4-f2d2-9cf0-51b3-4fd2cbedee61@ashroe.eu> Date: Fri, 25 Oct 2019 13:45:51 +0100 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: <10410603.iXVFKWJQZn@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 v6 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 24/10/2019 01:43, Thomas Monjalon wrote: > 27/09/2019 18:54, Ray Kinsella: >> This policy change introduces major ABI versions, these are >> declared every year, typically aligned with the LTS release >> and are supported by subsequent releases in the following year. > > No, the ABI number may stand for more than one year. ok, I will remove the reference to one year here. Just on a point of order, what was approved by the technical board was `one year`, initially. So the ABI Policy at this point in time is stability for `one year`. I tried to make the `one year` point in as few places as possible. Simply to reduce the rework later, when we lengthen the abi support period. I also include a note up front, making it abundantly clear the intention to lengthen the support period, as follows. "In 2019, the DPDK community stated it’s intention to move to ABI stable releases, over a number of release cycles. Beginning 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." > >> This change is intended to improve ABI stabilty for those projects >> consuming DPDK. >> >> Signed-off-by: Ray Kinsella >> --- >> doc/guides/contributing/abi_policy.rst | 321 +++++++++++++++------ >> .../contributing/img/abi_stability_policy.png | Bin 0 -> 61277 bytes >> doc/guides/contributing/img/what_is_an_abi.png | Bin 0 -> 151683 bytes > > As an Open Source project, binary files are rejected :) > Please provide the image source as SVG if the diagram is really required. ACK, done > > [...] >> +#. Major ABI versions are declared every **year** and are then supported for one >> + year, typically aligned with the :ref:`LTS release `. > > As discussed on the cover letter, please avoid making "every year" cadence, the rule. It's very hard to remove this one, what should can we say instead? #. Major ABI versions are declared on some cadence and are then supported for some period unknown, typically aligned with the `LTS release `. > >> +#. The ABI version is managed at a project level in DPDK, with the ABI version >> + reflected in all :ref:`library's soname `. > > Should we make clear here that an experimental ABI change has no impact > on the ABI version number? Absolutely, see four points below. #. Libraries or APIs marked as :ref:`Experimental ` are not considered part of an ABI version and may change without constraint. >> +#. The ABI should be preserved and not changed lightly. ABI changes must follow >> + the outlined :ref:`deprecation process `. >> +#. The addition of symbols is generally not problematic. The modification of >> + symbols is managed with :ref:`ABI Versioning `. >> +#. The removal of symbols is considered an :ref:`ABI breakage `, >> + once approved these will form part of the next ABI version. >> +#. Libraries or APIs marked as :ref:`Experimental ` are not >> + considered part of an ABI version and may change without constraint. >> +#. Updates to the :ref:`minimum hardware requirements `, which drop >> + support for hardware which was previously supported, should be treated as an >> + ABI change. >> + >> +.. note:: >> + >> + In 2019, the DPDK community stated it's intention to move to ABI stable >> + releases, over a number of release cycles. Beginning with maintaining ABI >> + stability through one year of DPDK releases starting from DPDK 19.11. > > There is no verb in this sentence. ACK, done. > >> + This >> + policy will be reviewed in 2020, with intention of lengthening the stability >> + period. > >> +What is an ABI version? >> +~~~~~~~~~~~~~~~~~~~~~~~ >> + >> +An ABI version is an instance of a library's ABI at a specific release. Certain >> +releases are considered by the community to be milestone releases, the yearly >> +LTS for example. Supporting those milestone release's ABI for some number of >> +subsequent releases is desirable to facilitate application upgrade. Those ABI >> +version's aligned with milestones release are therefore called 'ABI major >> +versions' and are supported for some number of releases. > > If you understand this paragraph, please raise your hand :) We can simplify as follows. An ABI version is an instance of a library's ABI at a specific release. Certain releases are considered to be milestone releases, the yearly LTS release for example. The ABI of a milestone release may be designated as a 'major ABI version', where this ABI version is then supported for some number of subsequent releases. Major ABI version support in subsequent releases facilitates application upgrade, by enabling applications built against the milestone release, to upgrade to subsequent releases of the library without a rebuild. > >> +More details on major ABI version can be found in the :ref:`ABI versioning >> +` guide. >> >> The DPDK ABI policy >> -~~~~~~~~~~~~~~~~~~~ >> +------------------- >> + >> +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. > > Again, the "one year" limit should not be documented as a general rule. As I said above, it's not obvious to me what I would say in its place. Can we leave as is until the community agree to lengthen the period? > >> +At the declaration of a major ABI version, major version numbers encoded in >> +libraries soname's 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``. >> >> +The ABI may then change multiple times, without warning, between the last major >> +ABI version increment and the HEAD label of the git tree, with the condition >> +that ABI compatibility with the major ABI version is preserved and therefore >> +soname's do not change. >> >> +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``. > > I don't understand the benefit of having a minor ABI version number. > Can we just have v20 and v21 as we discussed in the techboard? > Is it because an application linked with v20.2 cannot work with v20.1? You need to have minor versions for forward compatibility. So let's say v20 is the major ABI in v19.11. However a new function `rte_foobar` get's added in DPDK v20.02. `rte_foobar` is no longer experimental. I write a new application `funet` what _needs_ `rte_foobar`. The only way I can tell I have gotten the right library version, to satisfy `funet`s dependencies is the minor version number. In this case `funet`s author can also have a reasonable expectation, that `rte_foobar` will become part of the next `major ABI version`. > > If we must have a minor number, I suggest a numbering closer to release numbers: > release 19.11 -> ABI 19.11 > release 20.02 -> ABI 19.14 > release 20.05 -> ABI 19.17 > release 20.08 -> ABI 19.20 > It shows the month number as if the first year never finishes. > And when a new ABI is declared, release and ABI versions are the same: > release 20.11 -> ABI 20.11 What was agreed at the technical board is that DPDK v19.11 is ABI v20. Minor numbers are usually incremental, and release numbers do not need to co-relate with ABI version numbers. We previously discussed that v20.1 = LTS + 1 release = v20.02 v20.2 = LTS + 2 release = v20.05 All that said. I am very eager not to get into describing release management in the ABI policy. ABI policy is enough to describe with detail DPDKs release management also. > > >> +ABI versions, are supported by each release until such time as the next major >> +ABI version is declared. At that time, the deprecation of the previous major ABI >> +version will be noted in the Release Notes with guidance on individual symbol >> +depreciation and upgrade notes provided. > > I suggest a rewording: > " > An ABI version is supported in all new releases > until the next major ABI version is declared. > When changing the major ABI version, > the release notes give details about all ABI changes. > " ACK, happy to change, much of that wording was reuse from the old policy. > [...] >> + - The acknowledgment of a member of the technical board, as a delegate of the >> + `technical board `_ acknowledging the >> + need for the ABI change, is also mandatory. > > Only one? What about 3 members minimum? My feeling is that that three would become a real headache over time. Limit the techboards ability to scale, with each change requiring three ACKs from them. I am happy to change it, if you feel strongly. > > [...] >> +#. If a newly proposed API functionally replaces an existing one, when the new >> + API becomes non-experimental, then the old one is marked with >> + ``__rte_deprecated``. >> + >> + - The depreciated API should follow the notification process to be removed, >> + see :ref:`deprecation_notices`. >> + >> + - At the declaration of the next major ABI version, those ABI changes then >> + become a formal part of the new ABI and the requirement to preserve ABI >> + compatibility with the last major ABI version is then dropped. >> + >> + - The responsibility for removing redundant ABI compatibility code rests >> + with the original contributor of the ABI changes, failing that, then with >> + the contributor's company and then finally with the maintainer. > > Having too many responsibles look like nobody is really responsible. > I would tend to think that only the maintainer is responsible, > but he can ask for help. Others had specifically asked that the chain of responsibility be very clear, so that all the burden for excising redundant code does not fall automatically on the maintainer.