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

[Kinsella, Ray]

On 30/06/2021 20:56, Tyler Retzlaff wrote:
> On Tue, Jun 29, 2021 at 07:38:05PM +0100, Kinsella, Ray wrote:
>>
>>
>>>> +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.
> 
> a time based strategy works but i guess the follow-on to that is how is
> the clock tracked and how does it get updated? i don't think trying to
> troll through git history will be effective.
> 
> one nit, i think "api signature" doesn't cover all cases of what i would
> regard as change. i would prefer to define it as "no change where api/abi
> compatibility or semantic change occurred"? which is a lot more strict
> but in practice is necessary to support binaries when abi/api is stable.
> 
> i.e. if a recompile is necessary with or without code change then it's a
> change.

Having thought a bit ... this becomes a bit problematic.

Many data-structures in DPDK are nested, 
these can have a ripple effect when changed - a change to mbuf is a good example.

What I saying is ...
I don't think changes in ABI due to in-direct reasons should count.
If there is a change due to a deliberate change in the ABI signature 
that is fine, reset the clock.

If there is a change due to some nested data-structure, 
3-levels down changing in my book that doesn't count. 
As that may or may not have been deliberate, and is almost impossible to police. 

Checking anything but a deliberate change to the ABI signature,
would be practically impossible IMHO. 

> 
>>
>> However equally any changes to the implementation do not reset the clock.
>>
>> Would that work?
> 
> that works for me.

v2 on the way.

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