Re: [dpdk-dev] [PATCH v1 2/2] doc: clarify alias to experimental period

[Thomas Monjalon <thomas@monjalon.net>]

07/07/2020 16:45, Ray Kinsella:
> Clarify retention period for aliases to experimental.
> 
> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
> ---
> --- a/doc/guides/contributing/abi_versioning.rst
> +++ b/doc/guides/contributing/abi_versioning.rst
> @@ -158,7 +158,7 @@ The macros exported are:
>  * ``VERSION_SYMBOL_EXPERIMENTAL(b, e)``: Creates a symbol version table entry
>    binding versioned symbol ``b@EXPERIMENTAL`` to the internal function ``be``.
>    The macro is used when a symbol matures to become part of the stable ABI, to
> -  provide an alias to experimental for some time.
> +  provide an alias to experimental until the next major ABI version.

Why limiting the period for experimental status?
Some API want to remain experimental longer.

[...]
>  In situations in which an ``experimental`` symbol has been stable for some time,
>  and it becomes a candidate for promotion to the stable ABI. At this time, when
> -promoting the symbol, maintainer may choose to provide an alias to the
> -``experimental`` symbol version, so as not to break consuming applications.
> +promoting the symbol, the maintainer may choose to provide an alias to the
> +``experimental`` symbol version, so as not to break consuming applications. This

Please start a sentence on a new line.

> +alias will then typically be dropped in the next major ABI version.

I don't see the need for the time estimation.