From mboxrd@z Thu Jan  1 00:00:00 1970
From: Kevin Traynor <ktraynor@redhat.com>
Subject: Re: [PATCH v3 3/3] doc: add deprecation marker usage
Date: Thu, 24 Jan 2019 00:07:22 +0100
Message-ID: <bb2c1c5d-47d1-27a0-e5d8-a546a02bd4a2@redhat.com>
References: <20181221155719.89773-1-ferruh.yigit@intel.com>
 <20190122162310.53613-1-ferruh.yigit@intel.com>
 <20190122162310.53613-3-ferruh.yigit@intel.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit
Cc: Luca Boccassi <bluca@debian.org>, Yongseok Koh <yskoh@mellanox.com>,
 Neil Horman <nhorman@tuxdriver.com>
To: Ferruh Yigit <ferruh.yigit@intel.com>, dev@dpdk.org,
 John McNamara <john.mcnamara@intel.com>,
 Marko Kovacevic <marko.kovacevic@intel.com>
Return-path: <dev-bounces@dpdk.org>
Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28])
 by dpdk.org (Postfix) with ESMTP id 03E1B201
 for <dev@dpdk.org>; Thu, 24 Jan 2019 00:07:28 +0100 (CET)
In-Reply-To: <20190122162310.53613-3-ferruh.yigit@intel.com>
Content-Language: en-US
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
 <mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
Sender: "dev" <dev-bounces@dpdk.org>

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