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

[Kinsella, Ray]

On 29/06/2021 17:28, Tyler Retzlaff wrote:
> On Tue, Jun 29, 2021 at 05:00:31PM +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 ammendment 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 at ashroe.eu>
>> ---
>>  doc/guides/contributing/abi_policy.rst | 20 +++++++++++++++++---
>>  1 file changed, 17 insertions(+), 3 deletions(-)
>>
>> diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
>> index 4ad87dbfed..58bc45b8a5 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,16 @@ 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 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.

However equally any changes to the implementation do not reset the clock.

Would that work?

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