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

["Kinsella, Ray" <mdr@ashroe.eu>]

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.
>>>
>>> [...]
>>>>  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.
>>>
>>>
>>
>> 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?