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

  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

v5:
Grammar fix
Rephrase API removal reminder
---
 doc/guides/contributing/versioning.rst | 9 +++++++++
 1 file changed, 9 insertions(+)
  

On 01/03/2019 17:32, 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>
> 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
> 
> v5:
> Grammar fix
> Rephrase API removal reminder
> ---
>  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 2fcb8bafd..30f8735ba 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 are removed completely just after the next LTS.
> +
> +Reminder that old API should follow deprecation process to be removed.
> +
>  
>  Experimental APIs
>  -----------------
> 

Acked-by: Kevin Traynor <ktraynor@redhat.com>

for series, again :-)
  

01/03/2019 18:40, Kevin Traynor:
> On 01/03/2019 17:32, 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>
> > Acked-by: Neil Horman <nhorman@tuxdriver.com>
> 
> Acked-by: Kevin Traynor <ktraynor@redhat.com>
> 
> for series, again :-)

Applied, thanks