[dpdk-dev,[PATCH,v5] 5/5] doc: Add ABI __experimental tag documentation

  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 | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
  

> -----Original Message-----
> From: Neil Horman [mailto:nhorman@tuxdriver.com]
> Sent: Monday, January 22, 2018 1:48 AM
> To: dev@dpdk.org
> Cc: Neil Horman <nhorman@tuxdriver.com>; Thomas Monjalon
> <thomas@monjalon.net>; Mcnamara, John <john.mcnamara@intel.com>;
> Richardson, Bruce <bruce.richardson@intel.com>
> Subject: [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation
> 
> 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>
> ...
> +Note that marking an API as experimental is a multi 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 __rte_experimental tag (see rte_compat.h).  The DPDK build
> +makefiles perform a check to ensure that the map file and the C code
> +reflect the same list of symbols.  This check can be circumvented by
> defining ALLOW_EXPERIMENTAL_API during compilation in the corresponding
> library Makefile.
> +
> +In addition to tagging the code with __rte_experimental, the doxygen
> +markup must also contain the EXPERIMENTAL string, and the MAINTAINER
> +file should note that the library contains EXPERIMENTAL APIs.
> +
>  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
> --
> 2.14.3

Thanks for the update, and this work in general.

The rendered docs would probably look a better better with __rte_experimental
and ALLOW_EXPERIMENTAL_API is fixed width backticks ``var`` but that is only
a "nice to have" so no need for a respin.

Acked-by: John McNamara <john.mcnamara@intel.com>
  

23/01/2018 11:35, Mcnamara, John:
> 
> > -----Original Message-----
> > From: Neil Horman [mailto:nhorman@tuxdriver.com]
> > Sent: Monday, January 22, 2018 1:48 AM
> > To: dev@dpdk.org
> > Cc: Neil Horman <nhorman@tuxdriver.com>; Thomas Monjalon
> > <thomas@monjalon.net>; Mcnamara, John <john.mcnamara@intel.com>;
> > Richardson, Bruce <bruce.richardson@intel.com>
> > Subject: [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation
> > 
> > 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>
> > ...
> > +Note that marking an API as experimental is a multi 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 __rte_experimental tag (see rte_compat.h).  The DPDK build
> > +makefiles perform a check to ensure that the map file and the C code
> > +reflect the same list of symbols.  This check can be circumvented by
> > defining ALLOW_EXPERIMENTAL_API during compilation in the corresponding
> > library Makefile.
> > +
> > +In addition to tagging the code with __rte_experimental, the doxygen
> > +markup must also contain the EXPERIMENTAL string, and the MAINTAINER
> > +file should note that the library contains EXPERIMENTAL APIs.
> > +
> >  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
> > --
> > 2.14.3
> 
> Thanks for the update, and this work in general.
> 
> The rendered docs would probably look a better better with __rte_experimental
> and ALLOW_EXPERIMENTAL_API is fixed width backticks ``var`` but that is only
> a "nice to have" so no need for a respin.

Backticks added on apply.

Also changed the last sentence from
	the MAINTAINER file should note that the library contains EXPERIMENTAL APIs.
to
	the MAINTAINERS file should note the EXPERIMENTAL libraries.
Indeed, the practice is to note only new libraries as experimental in
the MAINTAINERS files.