[dpdk-dev,[PATCH,v5] 5/5] doc: Add ABI __experimental tag documentation
Checks
Commit Message
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
> -----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.
@@ -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