[dpdk-dev] [PATCHv4 5/5] doc: Add ABI __experimental tag documentation

[Neil Horman]

On Sat, Jan 13, 2018 at 04:56:11PM +0100, Thomas Monjalon wrote:
> 13/01/2018 01:28, Neil Horman:
> > On Fri, Jan 12, 2018 at 03:55:10PM +0000, Ferruh Yigit wrote:
> > > 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?
> 
> There will be always cases where we are sure that the experimental step
> is not needed.
> Even if it is required and checked by a tool, we can ignore it, right?
> However, there is no big benefit of bypassing the experimental step.
> 
> I am for making mandatory the new API as experimental.
> We will handle the exceptions case by case if any.
> 
If the consensus is to require experimental marking by default, and grant
exceptions as needed, then I would strongly suggest that we do this in
checkpatch as I can modify it to warn people of added API's (which will be
reflected in the CI tool, if the CI group is still maintaining it), but we can
collectively ignore it if its so clearly trivial that it requires no
experimental addition (which I think may freqently be the case).

I'll start work on that on monday

Best
Neil