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. > >
