Re: [dpdk-dev] [PATCH v3 3/3] doc: add deprecation marker usage

[Kevin Traynor <ktraynor@redhat.com>]

On 01/24/2019 03:31 PM, Ferruh Yigit wrote:
> On 1/23/2019 11:07 PM, Kevin Traynor wrote:
>> On 01/22/2019 05:23 PM, Ferruh Yigit wrote:
>>> Define '__rte_deprecated' usage process.
>>>
>>> Suggests keeping old API with '__rte_deprecated' marker including
>>> next LTS, they will be removed just after the LTS release.
>>>
>>> Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
>>> Acked-by: Luca Boccassi <bluca@debian.org>
>>> ---
>>> Cc: Luca Boccassi <bluca@debian.org>
>>> Cc: Kevin Traynor <ktraynor@redhat.com>
>>> Cc: Yongseok Koh <yskoh@mellanox.com>
>>> Cc: Neil Horman <nhorman@tuxdriver.com>
>>>
>>> v2:
>>> * Rephrased as commented
>>>
>>> v3:
>>> * changed when to remove the deprecated API. It is now just after
>>> an LTS release, the motivation is to keep changes small in LTS.
>>> Based on techboard discussion:
>>> http://mails.dpdk.org/archives/dev/2019-January/123519.html
>>> ---
>>>  doc/guides/contributing/versioning.rst | 9 +++++++++
>>>  1 file changed, 9 insertions(+)
>>>
>>> diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst
>>> index bfc27fbe0..977d06c60 100644
>>> --- a/doc/guides/contributing/versioning.rst
>>> +++ b/doc/guides/contributing/versioning.rst
>>> @@ -125,6 +125,15 @@ added to the Release Notes:
>>>    these changes. Binaries using this library built prior to version 2.1 will
>>>    require updating and recompilation.
>>>  
>>> +New API replacing previous one
>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>> +
>>> +If a new API proposed functionally replaces an existing one, when the
>>> +new API becomes active then the old one is marked with ``__rte_deprecated``.
>>
>> I don't think it's clear what 'active' means here. Can it be re-phrased
>> as something like "..when the new API has it's experimental tag removed,
>> then the old one..".
> 
> This was what in my mind by 'active' but didn't want to create confusion with
> details, and really it doesn't matter the "experimental" detail, by any means if
> the new API is not 'active' we shouldn't mark the old one as 'deprecated'.
> 
> But agree can be defined better than 'active'. Do you have any suggestion here,
> 'GA', 'public', 'official', 'supported'?
> 

How about 'non-experimental' ? I think it would make it clear in meaning
for general reading and also avoid a mis-interpretation of what the
actual detail is.

>>
>> It might also be worth mentioning the reasoning behind this, perhaps
>> something like: This is so an application continues to be provided with
>> at least one stable (non-deprecated/non-experimental) API for this
>> functionality.
>>
>>> +Deprecated APIs removed completely just after the next LTS.
>>> +
>>> +Reminder that new API should follow deprecation process to become active.
>>> +
>>>  
>>>  Experimental APIs
>>>  -----------------
>>>
>>
>