From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga06.intel.com (mga06.intel.com [134.134.136.31]) by dpdk.org (Postfix) with ESMTP id 4B9BDA48D for ; Fri, 12 Jan 2018 12:50:15 +0100 (CET) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga003.fm.intel.com ([10.253.24.29]) by orsmga104.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 12 Jan 2018 03:50:14 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.46,348,1511856000"; d="scan'208";a="18673778" Received: from fyigit-mobl1.ger.corp.intel.com (HELO [10.237.220.48]) ([10.237.220.48]) by FMSMGA003.fm.intel.com with ESMTP; 12 Jan 2018 03:50:12 -0800 To: Neil Horman Cc: dev@dpdk.org, 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> <6a5b06ce-c824-93aa-da38-1085bbe0eaa1@intel.com> <20180111212930.GC6879@hmswarspite.think-freely.org> From: Ferruh Yigit Message-ID: Date: Fri, 12 Jan 2018 11:50:12 +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: <20180111212930.GC6879@hmswarspite.think-freely.org> 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: Fri, 12 Jan 2018 11:50:15 -0000 On 1/11/2018 9:29 PM, Neil Horman wrote: > 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 <...> >>> automatically marked as ``experimental`` to allow for a period of stabilization>>> before they become part of a tracked ABI. Full sentences for above statement: " Since changes to APIs are most likely immediately after their introduction, as users begin to take advantage of 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. " This part is not related to this patchset, but it will be hard to maintain above behavior, "automatically marked" is not automatic now and moving them to stable after one release is also not automatic. Do you have any suggestion on how to manage this, do you think can your script be expanded to cover these checks? >>> >>> +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. As far as I know how to mark an API as experimental is not documented. What do you think making a new section for this information? > >>> + >>> 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 >>> >> >>