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

Message ID 20180122014807.24654-6-nhorman@tuxdriver.com
State Accepted, archived
Headers show

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/Intel-compilation fail apply patch file failure

Commit Message

Neil Horman Jan. 22, 2018, 1:48 a.m. UTC
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(+)

Comments

Mcnamara, John Jan. 23, 2018, 10:35 a.m. UTC | #1
> -----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>
Thomas Monjalon Jan. 29, 2018, 9:42 p.m. UTC | #2
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.

Patch
diff mbox

diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst
index 400090628..b4de9ed04 100644
--- a/doc/guides/contributing/versioning.rst
+++ b/doc/guides/contributing/versioning.rst
@@ -50,6 +50,20 @@  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 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