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 8CAA7271 for ; Sat, 13 Jan 2018 01:28:57 +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 1ea9gg-0003Qu-Fa; Fri, 12 Jan 2018 19:28:52 -0500 Date: Fri, 12 Jan 2018 19:28:40 -0500 From: Neil Horman To: Ferruh Yigit Cc: dev@dpdk.org, thomas@monjalon.net, john.mcnamara@intel.com, bruce.richardson@intel.com Message-ID: <20180113002840.GA17575@neilslaptop.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> <20180111212930.GC6879@hmswarspite.think-freely.org> <20180112143707.GC20015@hmswarspite.think-freely.org> <2ba5be68-4d5d-9f37-e86a-fe23b6708056@intel.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <2ba5be68-4d5d-9f37-e86a-fe23b6708056@intel.com> User-Agent: Mutt/1.9.1 (2017-09-22) X-Spam-Score: -1.0 (-) 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: Sat, 13 Jan 2018 00:28:58 -0000 On Fri, Jan 12, 2018 at 03:55:10PM +0000, Ferruh Yigit wrote: > On 1/12/2018 2:37 PM, Neil Horman wrote: > > On Fri, Jan 12, 2018 at 11:50:12AM +0000, Ferruh Yigit wrote: > >> 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? > >> > > > > I would make the argument that this was never the case, but rather a statement > > of principle. I assert that because I can find no mechanism anywhere in our > > build system that 'automatically' documented or marked a new API as experimental > > (please correct me if I'm wrong here). I think this was more meant to be a > > directive to developers to do whatever coding was needed to preform such > > marking/documentation in whatever style/format was current. E.g. introducers of > > a new API should document everything as EXPERIMENTAL using the appropriate > > doxygen tag and version map tag. > > > > In answer to your question, While we might be able to expand my script to check > > for new API's and ensure they are marked as experimental, I don't think thats > > the right place to do it, because that script is run at build time, where the > > state of the tree is transient. A better place to do it would be with a git hook > > at checkin time, or in the checkpatch script to flag new apis as experimental > > right before those new API's are comitted. Though I'm not a huge fan of that > > either (at least not of the former suggestion). I say that because I think we > > need to allow developers the freedom to determine the supported status of any > > new API that they add. For example, it seems pretty clear that a new library > > might want to have its entire API marked as experimental, but someone adding a > > single new function to an existing API might be confident that the new function > > is needed and should be immediately supported.. > > > > I think the better solution is to define the use of the EXPERIMENTAL tag in the > > version map as the canonical location to define unstable API functions. Doing > > so immediately commits an author to ensuring that the corresponding function > > definitions are marked with the __experimental tags, which in turn will cause > > any downstream users to be alerted to the fact that they might be using those > > API's in their code, so they can take appropriate action. It still allows for > > the Documentation to be out of sync, but alerting authors doing development I > > think is the more important element here, as Documentation can be corrected more > > easily than code in the field. > > > > Thoughts? > > After this point agree to using EXPERIMENTAL tag in the version map as standard, > but it will be hard to maintain "API is experimental for first release" without > help of any automated tool. > I completely agree, in fact I would say it is impossible to do without tooling, with or without this change. I think we need to do 1 of 2 things: 1) Add some code to checkpatch.pl to put up a warning if any new apis are added without marking them as experimental 2) Change the documentation to be a suggestion rather than a requirement. I'll look into doing (1), but I'm wondering if (2) is the more flexible way to go. I'm hesitant to enforce the initial marking of new APIs as experimental. Thoughts? Neil