[dpdk-dev] [PATCH v4] doc: alias to experimental tag for stable apis
Kevin Traynor
ktraynor at redhat.com
Tue Feb 25 15:22:10 CET 2020
On 18/02/2020 10:46, Ray Kinsella wrote:
> When a maintainer is promoting an API to become part of the next major ABI
> version by removing the experimental tag, possibly a few releases in
> advance of the declaration of the next ABI version. The maintainer may
> choose to offer an alias to the experimental tag, as removing the tag
> before the declaration of the next major ABI version, would cause an ABI
> breakage for applications using the API.
>
> Signed-off-by: Ray Kinsella <mdr at ashroe.eu>
> ---
> doc/guides/contributing/abi_policy.rst | 10 ++++++++++
> 1 file changed, 10 insertions(+)
>
> diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
> index 05ca959..7ae7de7 100644
> --- a/doc/guides/contributing/abi_policy.rst
> +++ b/doc/guides/contributing/abi_policy.rst
> @@ -159,6 +159,11 @@ The requirements for changing the ABI are:
> ``experimental``, as described in the section on :ref:`Experimental APIs
> and Libraries <experimental_apis>`.
>
> + - In situations in which an ``experimental`` API has been stable for some
> + time. When promoting the API to become part of the next ABI version, the
> + maintainer may choose to provide an alias to the ``experimental`` tag, so
> + as not to break consuming applications.
> +
> #. 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``.
> @@ -317,6 +322,11 @@ not required. Though, an API should remain in experimental state for at least
> one release. Thereafter, the normal process of posting patch for review to
> mailing list can be followed.
>
> +After the experimental tag has been formally removed, a tree/sub-tree maintainer
> +may choose to offer an alias to the experimental tag so as not to break
> +applications using the API. The alias is then dropped at the declaration of next
> +major ABI version.
> +
> Libraries
> ~~~~~~~~~
>
>
Sounds good. It doesn't change the minimum contract but gives some
flexibility to deal with individual cases.
Acked-by: Kevin Traynor <ktraynor at redhat.com>
More information about the dev
mailing list