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 <[email protected]>
>> ---
>> 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.
>
