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

Message ID 20190124181019.17168-3-ferruh.yigit@intel.com
State Superseded, archived
Delegated to: Thomas Monjalon
Headers show
Series
  • [v4,1/3] doc: clean ABI/API policy guide
Related show

Checks

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

Commit Message

Ferruh Yigit Jan. 24, 2019, 6:10 p.m.
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>
Acked-by: Neil Horman <nhorman@tuxdriver.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>

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

v4:
change working around 'active':
s/active/non-experimental/
s/become active/be able to replace old API
---
 doc/guides/contributing/versioning.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

Comments

Thomas Monjalon Jan. 31, 2019, 5:17 p.m. | #1
24/01/2019 19:10, Ferruh Yigit:
> 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>
> Acked-by: Neil Horman <nhorman@tuxdriver.com>
[...]
> +New API replacing previous one
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +If a new API proposed functionally replaces an existing one, when the new API
> +becomes non-experimental then the old one is marked with ``__rte_deprecated``.
> +Deprecated APIs removed completely just after the next LTS.

APIs removed -> APIs are removed

> +
> +Reminder that new API should follow deprecation process to be able to replace old API.

This last sentence is not clear to me.
I think you mean the old API should follow deprecation process
to be removed (replaced).
Ferruh Yigit Feb. 1, 2019, 5:06 p.m. | #2
On 1/31/2019 5:17 PM, Thomas Monjalon wrote:
>> +
>> +Reminder that new API should follow deprecation process to be able to replace old API.
> This last sentence is not clear to me.
> I think you mean the old API should follow deprecation process
> to be removed (replaced).

Yes, we are trying to say same thing.

Deprecation process required for replacing API.
Thomas Monjalon March 1, 2019, 4:46 p.m. | #3
01/02/2019 18:06, Ferruh Yigit:
> On 1/31/2019 5:17 PM, Thomas Monjalon wrote:
> >> +
> >> +Reminder that new API should follow deprecation process to be able to replace old API.
> > This last sentence is not clear to me.
> > I think you mean the old API should follow deprecation process
> > to be removed (replaced).
> 
> Yes, we are trying to say same thing.
> 
> Deprecation process required for replacing API.

I think it is important to emphasize that the process applies to removal.

Patch

diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst
index bfc27fbe0..491fae438 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 non-experimental 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 be able to replace old API.
+
 
 Experimental APIs
 -----------------