On 6/30/2021 8:56 PM, Tyler Retzlaff wrote: > 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. >
We are grouping the new experimental APIs in the version file based on the release they are added with a comment, thanks to Dave. Like: # added in 19.02 rte_extmem_attach; rte_extmem_detach; rte_extmem_register; rte_extmem_unregister; # added in 19.05 rte_dev_dma_map; rte_dev_dma_unmap; .... Please check 'lib/eal/version.map' as sample. This enables us easily see the release experimental APIs are added. > 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. >>>