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

[Kinsella, Ray]

On 04/08/2021 11:39, Thomas Monjalon wrote:
> 04/08/2021 11:34, Ray Kinsella:
>> 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
> 
> s/conservation/conversation/
> 
>> maintainer and original contributor.
>>
>> Signed-off-by: Ray Kinsella <mdr at ashroe.eu>
>> Acked-by: Tyler Retzlaff <roretzla at linux.microsoft.com>
>> ---
>> +#. 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.
> [...]
>> +Promotion to stable
>> +~~~~~~~~~~~~~~~~~~~
>> +
>> +An API's ``experimental`` status should be reviewed annually, by both the
>> +maintainer and/or the original contributor. Ordinarily APIs marked as
>> +``experimental`` will be promoted to the stable ABI once a maintainer has become
>> +satisfied that the API is mature and is unlikely to change.
>> +
>> +In exceptional circumstances, should an API still be 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
>> +accumulation of abandoned symbols.
>> +
>> +Should an API's Binary Interface change, usually due to a direct change to the
> 
> API's Binary Interface?
> I assume you mean ABI.
> 
>> +API's signature, it is reasonable for the review and expiry clocks to reset. The
>> +promotion or removal of symbols will typically form part of a conversation
>> +between the maintainer and the original contributor.
> 
> Acked-by: Thomas Monjalon <thomas at monjalon.net>
> 
> Applied with above changes, thanks.
> 

Thanks.