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 <nhor...@tuxdriver.com> > >>>>> CC: Thomas Monjalon <tho...@monjalon.net> > >>>>> CC: "Mcnamara, John" <john.mcnam...@intel.com> > >>>>> CC: Bruce Richardson <bruce.richard...@intel.com> > >> > >> <...> > >> > >>>>> 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
