[dpdk-dev] [PATCH v1] doc: policy on promotion of experimental APIs

[Tyler Retzlaff]

On Tue, Jun 29, 2021 at 07:38:05PM +0100, Kinsella, Ray wrote:
> 
> 
> >> +Promotion to stable
> >> +~~~~~~~~~~~~~~~~~~~
> >> +
> >> +Ordinarily APIs marked as ``experimental`` will be promoted to the stable API
> >> +once a maintainer and/or the original contributor is satisfied that the API is
> >> +reasonably mature. In exceptional circumstances, should an API still be
> > 
> > this seems vague and arbitrary. is there a way we can have a more
> > quantitative metric for what "reasonably mature" means.
> > 
> >> +classified as ``experimental`` after two years and is without any prospect of
> >> +becoming part of the stable API. The API will then become a candidate for
> >> +removal, to avoid the acculumation of abandoned symbols.
> > 
> > i think with the above comment the basis for removal then depends on
> > whatever metric is used to determine maturity. 
> > if it is still changing
> > then it seems like it is useful and still evolving so perhaps should not
> > be removed but hasn't changed but doesn't meet the metric for being made
> > stable then perhaps it becomes a candidate for removal.
> 
> Good idea. 
> 
> I think it is reasonable to add a clause that indicates that any change 
> to the "API signature" would reset the clock.

a time based strategy works but i guess the follow-on to that is how is
the clock tracked and how does it get updated? i don't think trying to
troll through git history will be effective.

one nit, i think "api signature" doesn't cover all cases of what i would
regard as change. i would prefer to define it as "no change where api/abi
compatibility or semantic change occurred"? which is a lot more strict
but in practice is necessary to support binaries when abi/api is stable.

i.e. if a recompile is necessary with or without code change then it's a
change.

> 
> However equally any changes to the implementation do not reset the clock.
> 
> Would that work?

that works for me.

> 
> > 
> >> +
> >> +The promotion or removal of symbols will typically form part of a conversation
> >> +between the maintainer and the original contributor.
> > 
> > this should extend beyond just symbols. there are other changes that
> > impact the abi where exported symbols don't change. e.g. additions to
> > return values sets.> 
> > thanks for working on this.
> >