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

On 11/07/2021 08:22, Jerin Jacob wrote:

On Sat, Jul 10, 2021 at 12:46 AM Tyler Retzlaff
[off-list ref] wrote:

quoted

On Fri, Jul 09, 2021 at 11:46:54AM +0530, Jerin Jacob wrote:

quoted

quoted

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