From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga01.intel.com (mga01.intel.com [192.55.52.88]) by dpdk.org (Postfix) with ESMTP id B9743A493 for ; Thu, 11 Jan 2018 21:06:51 +0100 (CET) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga002.fm.intel.com ([10.253.24.26]) by fmsmga101.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 11 Jan 2018 12:06:50 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.46,346,1511856000"; d="scan'208";a="9438673" Received: from fyigit-mobl1.ger.corp.intel.com (HELO [10.237.220.48]) ([10.237.220.48]) by fmsmga002.fm.intel.com with ESMTP; 11 Jan 2018 12:06:49 -0800 To: Neil Horman , dev@dpdk.org Cc: thomas@monjalon.net, john.mcnamara@intel.com, bruce.richardson@intel.com References: <20171201185628.16261-1-nhorman@tuxdriver.com> <20171213151728.16747-1-nhorman@tuxdriver.com> <20171213151728.16747-6-nhorman@tuxdriver.com> From: Ferruh Yigit Message-ID: <6a5b06ce-c824-93aa-da38-1085bbe0eaa1@intel.com> Date: Thu, 11 Jan 2018 20:06:48 +0000 User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:52.0) Gecko/20100101 Thunderbird/52.5.2 MIME-Version: 1.0 In-Reply-To: <20171213151728.16747-6-nhorman@tuxdriver.com> Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 8bit 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 20:06:52 -0000 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. > + > 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 >