From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp.tuxdriver.com (charlotte.tuxdriver.com [70.61.120.58]) by dpdk.org (Postfix) with ESMTP id DB8B0A490 for ; Thu, 11 Jan 2018 22:29:41 +0100 (CET) Received: from [107.15.66.59] (helo=localhost) by smtp.tuxdriver.com with esmtpsa (TLSv1:AES256-SHA:256) (Exim 4.63) (envelope-from ) id 1eZkPj-0000k2-Gj; Thu, 11 Jan 2018 16:29:39 -0500 Date: Thu, 11 Jan 2018 16:29:31 -0500 From: Neil Horman To: Ferruh Yigit Cc: dev@dpdk.org, thomas@monjalon.net, john.mcnamara@intel.com, bruce.richardson@intel.com Message-ID: <20180111212930.GC6879@hmswarspite.think-freely.org> References: <20171201185628.16261-1-nhorman@tuxdriver.com> <20171213151728.16747-1-nhorman@tuxdriver.com> <20171213151728.16747-6-nhorman@tuxdriver.com> <6a5b06ce-c824-93aa-da38-1085bbe0eaa1@intel.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <6a5b06ce-c824-93aa-da38-1085bbe0eaa1@intel.com> User-Agent: Mutt/1.9.1 (2017-09-22) X-Spam-Score: -2.9 (--) X-Spam-Status: No Subject: Re: [dpdk-dev] [PATCHv4 5/5] doc: Add ABI __experimental tag documentation X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 11 Jan 2018 21:29:42 -0000 On Thu, Jan 11, 2018 at 08:06:48PM +0000, Ferruh Yigit wrote: > 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 > > CC: Thomas Monjalon > > CC: "Mcnamara, John" > > CC: Bruce Richardson > > --- > > 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. > Is that documented somewhere? I'd like to add this to the same location that it otherwise is written out. The above location was the only place in the guide that I could find reference to experimental markings. > > + > > 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 > > > >