[dpdk-dev] [PATCH] doc: alias to experimental tag for stable apis
Neil Horman
nhorman at tuxdriver.com
Tue Feb 25 16:35:40 CET 2020
On Wed, Feb 05, 2020 at 03:17:52PM +0000, 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..9a4a102 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 where 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.
> +
I don't have any issue with the approach, but just to ask the question, is it
worth providing an example here, of how exactly to do this? The use of
VERSION_SYMBOL isn't often used, and so may be non-obvious.
Actually, as I look at it, the VERSION_SYMBOL macro assume a DPDK_ prefix on the
version string, which works for versioned symbols, but not for the EXPERIMENTAL
symbol version (no DPDK_ prefix). We should probably create a variant of the
VERSION_SYMBOL macro to allow aliasing to the EXPERIMENTAL version, something
like ALIAS_TO_EXPERIMENTAL() or some such
Neil
> #. 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. This alias can then be dropped at the declaration of
> +next major ABI version.
> +
> Libraries
> ~~~~~~~~~
>
> --
> 2.7.4
>
>
More information about the dev
mailing list