diff mbox series

[RFC,2/2] doc: add deprecation marker usage

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

Checks

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

Commit Message

Ferruh Yigit Dec. 19, 2018, 12:52 p.m. UTC
Define '__rte_deprecated' usage process.

Suggests keeping old API with '__rte_deprecated' marker until next LTS.

Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
---
Cc: Luca Boccassi <bluca@debian.org>
Cc: Kevin Traynor <ktraynor@redhat.com>
Cc: Yongseok Koh <yskoh@mellanox.com>
Cc: Neil Horman <nhorman@tuxdriver.com>
---
 doc/guides/contributing/versioning.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

Comments

Luca Boccassi Dec. 20, 2018, 8:02 a.m. UTC | #1
On Wed, 2018-12-19 at 12:52 +0000, Ferruh Yigit wrote:
> Define '__rte_deprecated' usage process.
> 
> Suggests keeping old API with '__rte_deprecated' marker until next
> LTS.
> 
> Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
> ---
> Cc: Luca Boccassi <bluca@debian.org>
> Cc: Kevin Traynor <ktraynor@redhat.com>
> Cc: Yongseok Koh <yskoh@mellanox.com>
> Cc: Neil Horman <nhorman@tuxdriver.com>
> ---
>  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 19af56cd2..e0edd2e20 100644
> --- a/doc/guides/contributing/versioning.rst
> +++ b/doc/guides/contributing/versioning.rst
> @@ -128,6 +128,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
> new API becomes
> +active old one marked with ``__rte_deprecated`` until next LTS. In
> next LTS API
> +removed completely.
> +

Perhaps a bit of rephrasing, ie:

"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`` until the next LTS. In the next LTS, the API is
removed completely."

Other than that:

Acked-by: Luca Boccassi <bluca@debian.org>
Ferruh Yigit Dec. 21, 2018, 3:52 p.m. UTC | #2
On 12/20/2018 8:02 AM, Luca Boccassi wrote:
> On Wed, 2018-12-19 at 12:52 +0000, Ferruh Yigit wrote:
>> Define '__rte_deprecated' usage process.
>>
>> Suggests keeping old API with '__rte_deprecated' marker until next
>> LTS.
>>
>> Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
>> ---
>> Cc: Luca Boccassi <bluca@debian.org>
>> Cc: Kevin Traynor <ktraynor@redhat.com>
>> Cc: Yongseok Koh <yskoh@mellanox.com>
>> Cc: Neil Horman <nhorman@tuxdriver.com>
>> ---
>>  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 19af56cd2..e0edd2e20 100644
>> --- a/doc/guides/contributing/versioning.rst
>> +++ b/doc/guides/contributing/versioning.rst
>> @@ -128,6 +128,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
>> new API becomes
>> +active old one marked with ``__rte_deprecated`` until next LTS. In
>> next LTS API
>> +removed completely.
>> +
> 
> Perhaps a bit of rephrasing, ie:
> 
> "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`` until the next LTS. In the next LTS, the API is
> removed completely."

Thanks for suggestion, I will send a new version with this update.

> 
> Other than that:
> 
> Acked-by: Luca Boccassi <bluca@debian.org>
>
diff mbox series

Patch

diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst
index 19af56cd2..e0edd2e20 100644
--- a/doc/guides/contributing/versioning.rst
+++ b/doc/guides/contributing/versioning.rst
@@ -128,6 +128,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 new API becomes
+active old one marked with ``__rte_deprecated`` until next LTS. In next LTS API
+removed completely.
+
+Reminder that new API should follow deprecation process to become active.
+
 
 Experimental APIs
 -----------------