[dpdk-dev] [PATCH v3] doc: add section describing new abi versions
Thomas Monjalon
thomas at monjalon.net
Wed Aug 12 12:40:19 CEST 2020
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 <mdr at 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.
More information about the dev
mailing list