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 <m...@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 > >
