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 5231FA0613 for ; Wed, 25 Sep 2019 14:29:49 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id F09171BE3D; Wed, 25 Sep 2019 14:29:47 +0200 (CEST) Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by dpdk.org (Postfix) with ESMTP id F29D61B99D for ; Wed, 25 Sep 2019 14:29:45 +0200 (CEST) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 28BE0307D971; Wed, 25 Sep 2019 12:29:45 +0000 (UTC) Received: from [10.36.117.187] (ovpn-117-187.ams2.redhat.com [10.36.117.187]) by smtp.corp.redhat.com (Postfix) with ESMTP id 0BA715C1D4; Wed, 25 Sep 2019 12:29:34 +0000 (UTC) To: Ray Kinsella , dev@dpdk.org Cc: thomas@monjalon.net, 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, Luca Boccassi , David Marchand References: <1565864619-17206-1-git-send-email-mdr@ashroe.eu> <1565864619-17206-3-git-send-email-mdr@ashroe.eu> <81d2f70c-62dc-1a73-22a2-79317d09b2da@ashroe.eu> From: Kevin Traynor Message-ID: <3cfa4f0d-289b-68e6-74fe-3cee7c9e37d1@redhat.com> Date: Wed, 25 Sep 2019 13:29:33 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.7.0 MIME-Version: 1.0 In-Reply-To: <81d2f70c-62dc-1a73-22a2-79317d09b2da@ashroe.eu> Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.48]); Wed, 25 Sep 2019 12:29:45 +0000 (UTC) Subject: Re: [dpdk-dev] [PATCH v3 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/09/2019 12:32, Ray Kinsella wrote: >=20 > Thanks Kevin for working through all this. > Other comments are inline. >=20 > On 30/08/2019 17:20, Kevin Traynor wrote: >> Hi Ray, >> >> On 15/08/2019 11:23, Ray Kinsella wrote: >>> 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. >>> This change is intended to improve ABI stabilty for those projects >>> consuming DPDK. >>> >>> Signed-off-by: Ray Kinsella >>> --- >>> doc/guides/contributing/abi_policy.rst | 308 +++++++++++++++++++++++= +--------- >>> doc/guides/contributing/stable.rst | 38 ++-- >>> 2 files changed, 245 insertions(+), 101 deletions(-) >>> >>> diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/cont= ributing/abi_policy.rst >>> index 55bacb4..6190bdc 100644 >>> --- a/doc/guides/contributing/abi_policy.rst >>> +++ b/doc/guides/contributing/abi_policy.rst >>> @@ -1,33 +1,46 @@ >>> .. SPDX-License-Identifier: BSD-3-Clause >>> - Copyright 2018 The DPDK contributors >>> + Copyright 2019 The DPDK contributors >>> =20 >>> -.. abi_api_policy: >>> +.. _abi_policy: >>> =20 >>> -DPDK ABI/API policy >>> -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D >>> +ABI Policy >>> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D >>> =20 >>> Description >>> ----------- >>> =20 >>> -This document details some methods for handling ABI management in th= e DPDK. >>> +This document details the management policy that ensures the long-te= rm stability >>> +of the DPDK ABI and API. >>> =20 >>> General Guidelines >>> ------------------ >>> =20 >>> -#. Whenever possible, ABI should be preserved >>> -#. ABI/API may be changed with a deprecation process >>> -#. The modification of symbols can generally be managed with version= ing >>> -#. Libraries or APIs marked in ``experimental`` state may change wit= hout constraint >>> -#. New APIs will be marked as ``experimental`` for at least one rele= ase to allow >>> - any issues found by users of the new API to be fixed quickly >>> -#. The addition of symbols is generally not problematic >>> -#. The removal of symbols generally is an ABI break and requires bum= ping of the >>> - LIBABIVER macro >>> -#. Updates to the minimum hardware requirements, which drop support = for hardware which >>> - was previously supported, should be treated as an ABI change. >>> - >>> -What is an ABI >>> -~~~~~~~~~~~~~~ >>> +#. Major ABI versions are declared every **year** and are then suppo= rted for one >>> + year, typically aligned with the :ref:`LTS release `. >>> +#. The ABI version is managed at a project level in DPDK, with the A= BI version >>> + reflected in all :ref:`library's soname `. >>> +#. 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 modific= ation 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 constrai= nt. >>> +#. Updates to the :ref:`minimum hardware requirements `, w= hich drop >>> + support for hardware which was previously supported, should be tr= eated 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 maintai= ning ABI >>> + stability through one year of DPDK releases starting from DPDK 19= =2E11. This >>> + policy will be reviewed in 2020, with intention of lengthening th= e stability >>> + period. >>> + >>> +What is an ABI? >>> +~~~~~~~~~~~~~~~ >>> =20 >>> An ABI (Application Binary Interface) is the set of runtime interfac= es exposed >>> by a library. It is similar to an API (Application Programming Inter= face) but >>> @@ -39,30 +52,67 @@ Therefore, in the case of dynamic linking, it is = critical that an ABI is >>> preserved, or (when modified), done in such a way that the applicati= on is unable >>> to behave improperly or in an unexpected fashion. >>> =20 >>> +What is an ABI version? >>> +~~~~~~~~~~~~~~~~~~~~~~~ >>> =20 >>> -ABI/API Deprecation >>> -------------------- >>> +An ABI version is an instance of a library's ABI at a specific relea= se. Certain >>> +releases are considered by the community to be milestone releases, t= he yearly >>> +LTS for example. Supporting those milestone release's ABI for some n= umber 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. >>> + >>> +More details on major ABI version can be found in the :ref:`ABI vers= ioning >>> +` guide. >>> =20 >>> 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 yea= r by all >>> +subsequent releases within that time period, until the next LTS rele= ase, e.g. >>> +v20.11. >>> + >>> +At the declaration of a major ABI version, major version numbers enc= oded 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`` w= ould 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 c= ondition >>> +that ABI compatibility with the major ABI version is preserved and t= herefore >>> +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 t= his, might >>> +be that ``librte_eal.so.20.1`` would indicate the first ABI compatib= le DPDK >>> +release, following the declaration of the new major ABI version ``20= ``. >>> + >>> +ABI versions, are supported by each release until such time as the n= ext major >>> +ABI version is declared. At that time, the deprecation of the previo= us major ABI >>> +version will be noted in the Release Notes with guidance on individu= al symbol >>> +depreciation and upgrade notes provided. >>> =20 >>> -ABI versions are set at the time of major release labeling, and the = ABI may >>> -change multiple times, without warning, between the last release lab= el and the >>> -HEAD label of the git tree. >>> +.. _abi_changes: >>> =20 >>> -ABI versions, once released, are available until such time as their >>> -deprecation has been noted in the Release Notes for at least one maj= or release >>> -cycle. For example consider the case where the ABI for DPDK 2.0 has = been >>> -shipped and then a decision is made to modify it during the developm= ent of >>> -DPDK 2.1. The decision will be recorded in the Release Notes for the= DPDK 2.1 >>> -release and the modification will be made available in the DPDK 2.2 = release. >>> +ABI Changes >>> +~~~~~~~~~~~ >>> =20 >>> -ABI versions may be deprecated in whole or in part as needed by a gi= ven >>> -update. >>> +The ABI may still change after the declaration of a major ABI versio= n, that is >>> +new APIs may be still added or existing APIs may be modified. >>> =20 >>> -Some ABI changes may be too significant to reasonably maintain multi= ple >>> -versions. In those cases ABI's may be updated without backward compa= tibility >>> -being provided. The requirements for doing so are: >>> +.. Warning:: >>> + >>> + Note that, the process for ABI deprecation should not be undertak= en lightly. >>> + ABI stability is extremely important for downstream consumers of = the DPDK, >> >>> + especially when distributed in shared object form. Every effort s= hould be >>> + made to preserve the ABI whenever possible. The ABI should only b= e changed >>> + for significant reasons, such as performance enhancements. ABI br= eakage due >>> + to changes such as reorganizing public structure fields for aesth= etic or >>> + readability purposes should be avoided. >>> + >> >> This text is not changed and it reads like *any* performance enhanceme= nt >> is a good enough reason for an ABI break. Can't obviously quantify it,= >> but maybe "major performance enhancement" is closer to the intended >> tone? Sorry for nit-picking over one word! >=20 > I agree, I was in two minds about whether to clarify this section or if= > it was fine as-is. I left it there as a general warning to stop and > think before you ask to change the ABI. A performance gain alone doesn'= t > absolve the contributor from an obligation to preserve ABI compatibilit= y. >=20 > Perhaps reword as follows? >=20 > .. Warning:: >=20 > Note that, this policy details the method by which the ABI may be > changed, with due regard to preserving compatibility and observing > depreciation notices. This process however should not be undertaken > lightly, as a general rule ABI stability is extremely important for > downstream consumers of DPDK. The ABI should only be changed for > significant reasons, such as performance enhancements. ABI breakages du= e > to changes such as reorganizing public structure fields for aesthetic o= r > readability purposes should be avoided. >=20 Hi Ray, ok, thanks for checking it. >> >>> + >>> +The requirements for changing the ABI are: >>> =20 >>> #. At least 3 acknowledgments of the need to do so must be made on t= he >>> dpdk.org mailing list. >>> @@ -71,34 +121,119 @@ being provided. The requirements for doing so a= re: >>> no maintainer is available for the component, the tree/sub-tree= maintainer >>> for that component must acknowledge the ABI change instead. >>> =20 >>> + - The acknowledgment of a member of the technical board, as a del= egate of the >>> + `technical board `_ acknowled= ging the >>> + need for the ABI change, is also mandatory. >>> + >>> - It is also recommended that acknowledgments from different "are= as of >>> interest" be sought for each deprecation, for example: from NIC= vendors, >>> CPU vendors, end-users, etc. >>> =20 >>> -#. The changes (including an alternative map file) can be included w= ith >>> - 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 when it become the defau= lt ABI. >>> - More preferred way to provide this information is sending the fea= ture >>> - as a separate patch and reference it in deprecation notice. >>> +#. Backward compatibly with the major ABI version must be maintained= through >> >> s/compatibly/compatibility/ >=20 > ACK >=20 >> >>> + :ref:`abi_versioning`, with :ref:`forward-only ` co= mpatibility >>> + offered for any ABI changes that are indicated to be part of the = next ABI >>> + version. >>> =20 >>> -#. A full deprecation cycle, as explained above, must be made to off= er >>> - downstream consumers sufficient warning of the change. >>> + - In situations were backward compatibility is not possible, read= the >> >> s/were/where/ >=20 > ACK >=20 >> >>> + section on :ref:`abi_breakages`. >>> =20 >>> -Note that the above process for ABI deprecation should not be undert= aken >>> -lightly. ABI stability is extremely important for downstream consume= rs of the >>> -DPDK, especially when distributed in shared object form. Every effor= t should >>> -be made to preserve the ABI whenever possible. The ABI should only b= e changed >>> -for significant reasons, such as performance enhancements. ABI break= age due to >>> -changes such as reorganizing public structure fields for aesthetic o= r >>> -readability purposes should be avoided. >>> + - No backward or forward compatibility is offered for API changes= marked as >>> + ``experimental``, as described in the section on :ref:`Experime= ntal APIs >>> + and Libraries `. >>> =20 >>> -.. note:: >>> +#. If a newly proposed API functionally replaces an existing one, wh= en 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 ch= anges then >>> + become a formal part of the new ABI and the requirement to pre= serve ABI >>> + compatibility with the last major ABI version is then dropped.= >>> + >>> + - The responsibility for removing redundant ABI compatibility co= de rests >>> + with the original contributor of the ABI changes, failing that= , then with >>> + the contributor's company and then finally with the maintainer= =2E >>> + >>> +.. _forward-only: >>> + >>> +.. Note:: >>> + >>> + Note that forward-only compatibility is offered for those changes= made >>> + between major ABI versions. As a library's soname can only descri= be >>> + compatibility with the last major ABI version, until the next maj= or ABI >>> + version is declared, these changes therefore cannot be resolved a= s a runtime >>> + dependency through the soname. Therefore any application wishing = to make use >>> + of these ABI changes can only ensure that it's runtime dependenci= es are met >>> + through Operating System package versioning. >>> + >>> +.. _hw_rqmts: >>> + >>> +.. Note:: >>> =20 >>> Updates to the minimum hardware requirements, which drop support = for hardware >>> which was previously supported, should be treated as an ABI chang= e, and >>> - follow the relevant deprecation policy procedures as above: 3 ack= s and >>> - announcement at least one release in advance. >>> + follow the relevant deprecation policy procedures as above: 3 ack= s, technical >>> + board approval and announcement at least one release in advance. >>> + >>> +.. _abi_breakages: >>> + >>> +ABI Breakages >>> +~~~~~~~~~~~~~ >>> + >>> +For those ABI changes that are too significant to reasonably maintai= n multiple >>> +symbol versions, there is an amended process. In these cases, ABIs m= ay be >>> +updated without the requirement of backward compatibility being prov= ided. These >>> +changes must follow the `same process :ref:`described above ` as non-breaking >>> +changes, however with the following additional requirements: >>> + >>> +#. ABI breaking changes (including an alternative map file) can be i= ncluded with >>> + deprecation notice, in wrapped way by the ``RTE_NEXT_ABI`` option= , to provide >>> + more details about oncoming changes. ``RTE_NEXT_ABI`` wrapper wil= l be removed >>> + at the declaration of the next major ABI version. >>> + >>> +#. Once approved, and after the depreciation notice has been observe= d these >>> + changes will form part of the next declared major ABI version. >>> + >>> +Examples of ABI Changes >>> +~~~~~~~~~~~~~~~~~~~~~~~ >>> + >>> +The following are examples of allowable ABI changes occurring betwee= n >>> +declarations of major ABI versions. >>> + >>> +* DPDK 19.11 release, defines the function ``rte_foo()``, and ``rte_= foo()`` >>> + as part of the major ABI version ``20``. >>> + >>> +* DPDK 20.02 release defines a new function ``rte_foo(uint8_t bar)``= , and >>> + this is not a problem as long as the symbol ``rte_foo@DPDK20`` is >>> + preserved through :ref:`abi_versioning`. >>> + >>> + - The new function may be marked with the ``__rte_experimental`` t= ag for a >>> + number of releases, as described in the section :ref:`experiment= al_apis`. >>> + >>> + - Once ``rte_foo(uint8_t bar)`` becomes non-experimental ``rte_foo= ()`` is then >>> + declared as ``__rte_depreciated``, with an associated deprecatio= n notice >>> + provided. >>> + >>> +* DPDK 19.11 is not re-released to include ``rte_foo(uint8_t bar)``,= the new >>> + version of ``rte_foo`` only exists from DPDK 20.02 onwards as desc= ribed in the >>> + :ref:`note on forward-only compatibility`. >>> + >>> +* DPDK 20.02 release defines the experimental function ``__rte_exper= imental >>> + rte_baz()``. This function may or may not exist in the DPDK 20.05 = release. >>> + >>> +* An application ``dPacket`` wishes to use ``rte_foo(uint8_t bar)``,= before the >>> + declaration of the DPDK ``21`` major API version. The application = can only >>> + ensure it's runtime dependencies are met by specifying ``DPDK (>=3D= 20.2)`` as >>> + an explicit package dependency, as the soname only may only indica= te the >>> + supported major ABI version. >>> + >>> +* At the release of DPDK 20.11, the function ``rte_foo(uint8_t bar)`= ` becomes >>> + formally part of then new major ABI version DPDK 21.0 and ``rte_fo= o()`` may be >>> + removed. >>> + >>> +.. _deprecation_notices: >>> =20 >>> Examples of Deprecation Notices >>> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ >>> @@ -106,46 +241,42 @@ Examples of Deprecation Notices >>> The following are some examples of ABI deprecation notices which wou= ld be >>> added to the Release Notes: >>> =20 >>> -* The Macro ``#RTE_FOO`` is deprecated and will be removed with vers= ion 2.0, >>> - to be replaced with the inline function ``rte_foo()``. >>> +* The Macro ``#RTE_FOO`` is deprecated and will be removed with ABI = version >>> + 21, to be replaced with the inline function ``rte_foo()``. >>> =20 >>> * The function ``rte_mbuf_grok()`` has been updated to include a new= parameter >>> - in version 2.0. Backwards compatibility will be maintained for thi= s function >>> - until the release of version 2.1 >>> + in version 20.2. Backwards compatibility will be maintained for th= is function >>> + until the release of the new DPDK major ABI version 21, in DPDK ve= rsion >>> + 20.11. >>> =20 >>> -* The members of ``struct rte_foo`` have been reorganized in release= 2.0 for >>> +* The members of ``struct rte_foo`` have been reorganized in DPDK 20= =2E02 for >>> performance reasons. Existing binary applications will have backwa= rds >>> - compatibility in release 2.0, while newly built binaries will need= to >>> - reference the new structure variant ``struct rte_foo2``. Compatibi= lity will >>> - be removed in release 2.2, and all applications will require updat= ing and >>> + compatibility in release 20.02, while newly built binaries will ne= ed to >>> + reference the new structure variant ``struct rte_foo2``. Compatibi= lity will be >>> + removed in release 20.11, and all applications will require updati= ng and >>> rebuilding to the new structure at that time, which will be rename= d to the >>> original ``struct rte_foo``. >>> =20 >>> * Significant ABI changes are planned for the ``librte_dostuff`` lib= rary. The >>> - upcoming release 2.0 will not contain these changes, but release 2= =2E1 will, >>> + upcoming release 20.02 will not contain these changes, but release= 20.11 will, >>> and no backwards compatibility is planned due to the extensive nat= ure of >>> - these changes. Binaries using this library built prior to version = 2.1 will >>> + these changes. Binaries using this library built prior to ABI vers= ion 21 will >>> require updating and recompilation. >>> =20 >>> -New API replacing previous one >>> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ >>> - >>> -If a new API proposed functionally replaces an existing one, when th= e new API >>> -becomes non-experimental then the old one is marked with ``__rte_dep= recated``. >>> -Deprecated APIs are removed completely just after the next LTS. >>> - >>> -Reminder that old API should follow deprecation process to be remove= d. >>> +.. _experimental_apis: >>> =20 >>> +Experimental >>> +------------ >>> =20 >>> -Experimental APIs >>> ------------------ >>> +APIs >>> +~~~~ >>> =20 >>> -APIs marked as ``experimental`` are not considered part of the ABI a= nd may >>> -change without warning at any time. Since changes to APIs are most = likely >>> -immediately after their introduction, as users begin to take advanta= ge of >>> -those new APIs and start finding issues with them, new DPDK APIs wil= l be >>> -automatically marked as ``experimental`` to allow for a period of st= abilization >>> -before they become part of a tracked ABI. >>> +APIs marked as ``experimental`` are not considered part of an ABI ve= rsion and >>> +may change without warning at any time. Since changes to APIs are mo= st likely >>> +immediately after their introduction, as users begin to take advanta= ge of those >>> +new APIs and start finding issues with them, new DPDK APIs will be a= utomatically >>> +marked as ``experimental`` to allow for a period of stabilization be= fore they >>> +become part of a tracked ABI version. >>> =20 >>> Note that marking an API as experimental is a multi step process. >>> To mark an API as experimental, the symbols which are desired to be = exported >>> @@ -163,7 +294,16 @@ In addition to tagging the code with ``__rte_exp= erimental``, >>> the doxygen markup must also contain the EXPERIMENTAL string, >>> and the MAINTAINERS file should note the EXPERIMENTAL libraries. >>> =20 >>> -For removing the experimental tag associated with an API, deprecatio= n notice >>> -is not required. Though, an API should remain in experimental state = for at least >>> -one release. Thereafter, normal process of posting patch for review = to mailing >>> -list can be followed. >>> +For removing the experimental tag associated with an API, deprecatio= n notice is >>> +not required. Though, an API should remain in experimental state for= at least >>> +one release. Thereafter, the normal process of posting patch for rev= iew to >>> +mailing list can be followed. >>> + >>> +Libraries >>> +~~~~~~~~~ >>> + >>> +Libraries marked as ``experimental`` are entirely not considered par= t of an ABI >>> +version, and may change without warning at any time. Experimental li= braries >>> +always have a major version of ``0`` to indicate they exist outside = of >>> +:ref:`abi_versioning` , with the minor version incremented with each= ABI change >>> +to library. >>> diff --git a/doc/guides/contributing/stable.rst b/doc/guides/contribu= ting/stable.rst >>> index 6a5eee9..d95c200 100644 >>> --- a/doc/guides/contributing/stable.rst >>> +++ b/doc/guides/contributing/stable.rst >>> @@ -1,7 +1,7 @@ >>> .. SPDX-License-Identifier: BSD-3-Clause >>> Copyright 2018 The DPDK contributors >>> =20 >>> -.. stable_lts_releases: >>> +.. _stable_lts_releases: >>> =20 >>> DPDK Stable Releases and Long Term Support >>> =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D >>> @@ -53,6 +53,9 @@ year's November (X.11) release will be maintained a= s an LTS for 2 years. >>> After the X.11 release, an LTS branch will be created for it at >>> http://git.dpdk.org/dpdk-stable where bugfixes will be backported to= =2E >>> =20 >>> +A LTS release may align with the declaration of a new major ABI vers= ion, >>> +please read the :ref:`abi_policy` for more information. >>> + >> >> Above is worth to mention, but as discussed on call earlier today, the= >> changes below should be dropped from this patchset. At present each LT= S >> minor release (e.g. 18.11.2) maintains the API/ABI of the original LTS= >> release (e.g. 18.11) and that is not changing. >=20 > ACK, I will remove >=20 >> >> What type of non-ABI breaking things are backported to LTS branches ca= n >> be discussed during the LTS presentation in DPDK userspace. >=20 > Do you anticipate any updates here? >=20 I should probably update it to add some more info, similar to one of the slides from Bordeaux re examples etc. thanks, Kevin. > Thanks, >=20 > Ray K >=20 >> >> thanks, >> Kevin. >> >>> It is anticipated that there will be at least 4 releases per year of= the LTS >>> or approximately 1 every 3 months. However, the cadence can be short= er or >>> longer depending on the number and criticality of the backported >>> @@ -68,10 +71,13 @@ point the LTS branch will no longer be maintained= with no further releases. >>> What changes should be backported >>> --------------------------------- >>> =20 >>> -Backporting should be limited to bug fixes. All patches accepted on = the master >>> -branch with a Fixes: tag should be backported to the relevant stable= /LTS >>> -branches, unless the submitter indicates otherwise. If there are exc= eptions, >>> -they will be discussed on the mailing lists. >>> +Backporting is a naturally conservative activity, and therefore shou= ld only >>> +include bug fixes and support for new hardware, were adding support = does not >>> +necessitate DPDK ABI/API changes. >>> + >>> +All patches accepted on the master branch with a Fixes: tag should b= e backported >>> +to the relevant stable/LTS branches, unless the submitter indicates = otherwise. >>> +If there are exceptions, they will be discussed on the mailing lists= =2E >>> =20 >>> Fixes suitable for backport should have a ``Cc: stable@dpdk.org`` ta= g in the >>> commit message body as follows:: >>> @@ -86,13 +92,18 @@ commit message body as follows:: >>> Signed-off-by: Alex Smith >>> =20 >>> =20 >>> -Fixes not suitable for backport should not include the ``Cc: stable@= dpdk.org`` tag. >>> +Fixes not suitable for backport should not include the ``Cc: stable@= dpdk.org`` >>> +tag. >>> =20 >>> -Features should not be backported to stable releases. It may be acce= ptable, in >>> -limited cases, to back port features for the LTS release where: >>> +New features, with the exception of new hardware support, should not= be >>> +backported to stable releases. In the case of new hardware support o= r any other >>> +exceptional circumstances limited backporting maybe permitted to the= LTS release >>> +where: >>> =20 >>> -* There is a justifiable use case (for example a new PMD). >>> -* The change is non-invasive. >>> +* There is a justifiable use case, for example the change is require= d to support >>> + a new platform or device (for example a new PMD). >>> +* The change is ABI/API preserving, it does not present an obvious "= new feature" >>> + to end consumer. >>> * The work of preparing the backport is done by the proposer. >>> * There is support within the community. >>> =20 >>> @@ -119,10 +130,3 @@ A Stable Release will be released by: >>> list. >>> =20 >>> Stable releases are available on the `dpdk.org download page `_. >>> - >>> - >>> -ABI >>> ---- >>> - >>> -The Stable Release should not be seen as a way of breaking or circum= venting >>> -the DPDK ABI policy. >>>