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

[Ferruh Yigit]

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 at intel.com>
>> Acked-by: Luca Boccassi <bluca at debian.org>
>> ---
>> Cc: Luca Boccassi <bluca at debian.org>
>> Cc: Kevin Traynor <ktraynor at redhat.com>
>> Cc: Yongseok Koh <yskoh at mellanox.com>
>> Cc: Neil Horman <nhorman at 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'?

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