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

[Honnappa Nagarahalli <Honnappa.Nagarahalli@arm.com>]

<snip>

> Subject: Re: [PATCH v1 2/2] doc: clarify alias to experimental period
> 
> 
> 
> On 07/07/2020 17:36, Thomas Monjalon wrote:
> > 07/07/2020 18:35, Kinsella, Ray:
> >> On 07/07/2020 16:26, Thomas Monjalon wrote:
> >>> 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.
This is not limiting the period. This is about how long VERSION_SYMBOL_EXPERIMENTAL should be in place for a symbol after the experimental tag is removed for the symbol.

> >>>
> >>> [...]
> >>>>  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.
> >>
> >> ACK
> >>
> >>>
> >>>> +alias will then typically be dropped in the next major ABI version.
> >>>
> >>> I don't see the need for the time estimation.
I prefer this wording as it clarifying what should be done while creating a patch.

> >>>
> >>>
> >>
> >> Will reword to ...
> >>
> >> "This alias will then be dropped in the next major ABI version."
> >
> > It is not addressing my first comment. Please see above.
> >
> 
> Thank you, I don't necessarily agree with the first comment :-) We need to say
> when the alias should be dropped no?