diff mbox series

[v3,3/3] doc: add deprecation marker usage

Message ID 20190122162310.53613-3-ferruh.yigit@intel.com (mailing list archive)
State Superseded, archived
Delegated to: Thomas Monjalon
Headers
Series [v3,1/3] doc: clean ABI/API policy guide |

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/Intel-compilation success Compilation OK

Commit Message

Ferruh Yigit Jan. 22, 2019, 4:23 p.m. UTC 
  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(+)

Comments

Kevin Traynor Jan. 23, 2019, 11:07 p.m. UTC | #1 
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..".

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
>  -----------------
>
Ferruh Yigit Jan. 24, 2019, 2:31 p.m. UTC | #2 
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'?

> 
> 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
>>  -----------------
>>
>
Kevin Traynor Jan. 24, 2019, 3:33 p.m. UTC | #3 
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
>>>  -----------------
>>>
>>
>
Ferruh Yigit Jan. 24, 2019, 4:29 p.m. UTC | #4 
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
>>>>  -----------------
>>>>
>>>
>>
>
diff mbox series

Patch

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``.
+Deprecated APIs removed completely just after the next LTS.
+
+Reminder that new API should follow deprecation process to become active.
+
 
 Experimental APIs
 -----------------