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 <m...@ashroe.eu> [...] > #. 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 <new_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 <stable_lts_releases>`. 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.
