From mboxrd@z Thu Jan  1 00:00:00 1970
From: Ferruh Yigit <ferruh.yigit@intel.com>
Subject: Re: [PATCHv4 5/5] doc: Add ABI __experimental tag
 documentation
Date: Thu, 11 Jan 2018 20:06:48 +0000
Message-ID: <6a5b06ce-c824-93aa-da38-1085bbe0eaa1@intel.com>
References: <20171201185628.16261-1-nhorman@tuxdriver.com>
 <20171213151728.16747-1-nhorman@tuxdriver.com>
 <20171213151728.16747-6-nhorman@tuxdriver.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
Cc: thomas@monjalon.net, john.mcnamara@intel.com, bruce.richardson@intel.com
To: Neil Horman <nhorman@tuxdriver.com>, dev@dpdk.org
Return-path: <dev-bounces@dpdk.org>
Received: from mga01.intel.com (mga01.intel.com [192.55.52.88])
 by dpdk.org (Postfix) with ESMTP id B9743A493
 for <dev@dpdk.org>; Thu, 11 Jan 2018 21:06:51 +0100 (CET)
In-Reply-To: <20171213151728.16747-6-nhorman@tuxdriver.com>
Content-Language: en-US
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://dpdk.org/ml/options/dev>,
 <mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://dpdk.org/ml/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://dpdk.org/ml/listinfo/dev>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
Sender: "dev" <dev-bounces@dpdk.org>

On 12/13/2017 3:17 PM, Neil Horman wrote:
> Document the need to add the __experimental tag to appropriate functions
> 
> Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> CC: Thomas Monjalon <thomas@monjalon.net>
> CC: "Mcnamara, John" <john.mcnamara@intel.com>
> CC: Bruce Richardson <bruce.richardson@intel.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 400090628..53f56397e 100644
> --- a/doc/guides/contributing/versioning.rst
> +++ b/doc/guides/contributing/versioning.rst
> @@ -50,6 +50,15 @@ those new APIs and start finding issues with them, new DPDK APIs will be
>  automatically marked as ``experimental`` to allow for a period of stabilization
>  before they become part of a tracked ABI.
>  
> +Note that marking an API as experimental is a two step process.  To mark an API
> +as experimental, the symbols which are desired to be exported must be placed in
> +an EXPERIMENTAL version block in the corresponding libraries' version map
> +script. Secondly, the corresponding definitions of those exported functions, and
> +their forward declarations (in the development header files), must be marked
> +with the __experimental tag (see rte_compat.h).  The DPDK build makefiles
> +preform a check to ensure that the map file and the C code reflect the same
> +list of symbols.

There are more steps we historically do to mark an API as experimental:
- Add to function header comment experimental for API documentation, preferably
with a warning tag to highlight it:

/**
 * @warning
 * @b EXPERIMENTAL:
....
 */

- If whole APIs in header file are experimental, add same experimental warning
doxygen comment in file comment, again preferably with warning.

- If whole library is experimental, put EXPERIMENTAL tag into maintainers file
as well.

> +
>  ABI versions, once released, are available until such time as their
>  deprecation has been noted in the Release Notes for at least one major release
>  cycle. For example consider the case where the ABI for DPDK 2.0 has been
>