Re: [dpdk-dev] [PATCH v3] doc: policy on the promotion of experimental APIs

["Kinsella, Ray" <mdr@ashroe.eu>]

On 11/07/2021 08:22, Jerin Jacob wrote:
> On Sat, Jul 10, 2021 at 12:46 AM Tyler Retzlaff
> <roretzla@linux.microsoft.com> wrote:
>>
>> On Fri, Jul 09, 2021 at 11:46:54AM +0530, Jerin Jacob wrote:
>>>> +
>>>> +Promotion to stable
>>>> +~~~~~~~~~~~~~~~~~~~
>>>> +
>>>> +Ordinarily APIs marked as ``experimental`` will be promoted to the stable ABI
>>>> +once a maintainer and/or the original contributor is satisfied that the API is
>>>> +reasonably mature. In exceptional circumstances, should an API still be
>>>
>>> Is this line with git commit message?
>>> Why making an exceptional case? why not make it stable after two years
>>> or remove it.
>>> My worry is if we make an exception case, it will be difficult to
>>> enumerate the exception case.
>>
>> i think the intent here is to indicate that an api/abi doesn't just
>> automatically become stable after a period of time.  there also has to
>> be an evaluation by the maintainer / community before making it stable.
>>
>> so i guess the timer is something that should force that evaluation. as
>> a part of that evaluation one would imagine there is justification for
>> keeping the api as experimental for longer and if so a rationale as to
>> why.
> 
> I think, we need to have a deadline. Probably one year timer for evaluation and
> two year for max time for decision to make it as stable or remove.
> 

Tyler is correct here (sorry for the delay I was out on vacation). 
In my usage of the word exception - I was conveying that an API aging or timing out should be an exceptional event.
What I am hoping will happen in the 90%-ile of cases is conveyed in the previous line. 

"Ordinarily APIs marked as ``experimental`` will be promoted to the stable ABI
once a maintainer and/or the original contributor is satisfied that the API is
reasonably mature."

i.e. that the symbol has be pro-actively managed with the maintainer and original author deciding when to promote.

I will add a line to indicate that experimental apis should be reviewed after one year.