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

[Ferruh Yigit <ferruh.yigit@intel.com>]

On 1/24/2019 3:33 PM, Kevin Traynor wrote:
> 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.

OK, I will send a new versions with s/active/non-experimental/

> 
>>>
>>> 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
>>>>  -----------------
>>>>
>>>
>>
>