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

[Tyler Retzlaff]

On Thu, Jul 01, 2021 at 08:56:22AM +0100, Ferruh Yigit wrote:
> 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.

this is fine but the subject being discussed is oriented around how long
an api/abi has been unchanged to identify it as a candidate for qualifying
it as stable (not experimental). are you suggesting that if api/abi changes
then it is moved to the -current version to "restart the clock" as it were?