[dpdk-dev] [PATCH] doc: alias to experimental tag for stable apis
david.marchand at redhat.com
Tue Feb 25 18:57:35 CET 2020
On Tue, Feb 25, 2020 at 4:36 PM Neil Horman <nhorman at tuxdriver.com> wrote:
> 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
Let's clarify this part so this can be merged in early 20.05.
More information about the dev