[v3] doc: policy on the promotion of experimental APIs

  Clarifying the ABI policy on the promotion of experimental APIS to stable.
We have a fair number of APIs that have been experimental for more than
2 years. This policy amendment indicates that these APIs should be
promoted or removed, or should at least form a conservation between the
maintainer and original contributor.

Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
---
v2: addressing comments on abi expiry from Tyler Retzlaff.
v3: addressing typos in the git commit message

 doc/guides/contributing/abi_policy.rst | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)
  

On Thu, Jul 01, 2021 at 11:38:42AM +0100, Ray Kinsella wrote:
> Clarifying the ABI policy on the promotion of experimental APIS to stable.
> We have a fair number of APIs that have been experimental for more than
> 2 years. This policy amendment indicates that these APIs should be
> promoted or removed, or should at least form a conservation between the
> maintainer and original contributor.
> 
> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
> ---
Acked-By: Tyler Retzlaff <roretzla@microsoft.com>
  

On Thu, Jul 1, 2021 at 4:08 PM Ray Kinsella <mdr@ashroe.eu> wrote:
>
> Clarifying the ABI policy on the promotion of experimental APIS to stable.
> We have a fair number of APIs that have been experimental for more than
> 2 years. This policy amendment indicates that these APIs should be
> promoted or removed, or should at least form a conservation between the
> maintainer and original contributor.
>
> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
> ---
> v2: addressing comments on abi expiry from Tyler Retzlaff.
> v3: addressing typos in the git commit message
>
>  doc/guides/contributing/abi_policy.rst | 22 +++++++++++++++++++---
>  1 file changed, 19 insertions(+), 3 deletions(-)
>
> diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
> index 4ad87dbfed..840c295e5d 100644
> --- a/doc/guides/contributing/abi_policy.rst
> +++ b/doc/guides/contributing/abi_policy.rst
> @@ -26,9 +26,10 @@ General Guidelines
>     symbols is managed with :ref:`ABI Versioning <abi_versioning>`.
>  #. The removal of symbols is considered an :ref:`ABI breakage <abi_breakages>`,
>     once approved these will form part of the next ABI version.
> -#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may
> -   be changed or removed without prior notice, as they are not considered part
> -   of an ABI version.
> +#. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may be
> +   changed or removed without prior notice, as they are not considered part of
> +   an ABI version. The :ref:`experimental <experimental_apis>` status of an API
> +   is not an indefinite state.
>  #. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop
>     support for hardware which was previously supported, should be treated as an
>     ABI change.
> @@ -358,3 +359,18 @@ Libraries
>  Libraries marked as ``experimental`` are entirely not considered part of an ABI
>  version.
>  All functions in such libraries may be changed or removed without prior notice.
> +
> +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.

> +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.
> +
> +Should an API's Binary Interface change during the two year period, usually due
> +to a direct change in the to API's signature. It is reasonable for the expiry
> +clock to reset. The promotion or removal of symbols will typically form part of
> +a conversation between the maintainer and the original contributor.
> --
> 2.26.2
>
  

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.
  

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.
  

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.