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

[Kinsella, Ray]

On 07/07/2020 18:00, Thomas Monjalon wrote:
> 07/07/2020 18:55, Honnappa Nagarahalli:
>>> 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 at 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 at 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.
> 
> Oh wait, I was wrong. It is only about the alias which is set
> AFTER the experimental period.
> 
>>>>>> [...]
>>>>>>>  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.
> 
> Yes, after a second read, I am OK.
> 
perfect, I will sort out the other bits.