Re: [dpdk-dev] [PATCH v8 2/4] doc: changes to abi policy introducing major abi versions

[Ray Kinsella <mdr@ashroe.eu>]

On 06/11/2019 21:07, Thomas Monjalon wrote:
> Hi,
> Please find the techboard comments below.
> 
> 06/11/2019 10:22, Ray Kinsella:
>> On 06/11/2019 09:06, Thomas Monjalon wrote:
>>> 06/11/2019 09:49, Ray Kinsella:
>>>> On 06/11/2019 00:11, Thomas Monjalon wrote:
>>>>> 05/11/2019 16:24, Ray Kinsella:
>>>>>> +#. Major ABI versions are declared every **year** and are then supported for one
>>>>>> +   year, typically aligned with the :ref:`LTS release <stable_lts_releases>`.
>>>>>
>>>>> As discussed earlier, a major ABI version can be declared less often
>>>>> than one year in the future.
>>>>> An ABI is supported more than one year, because of the LTS branches.
>>>>> That's why I propose to replace with this sentence:
>>>>> "
>>>>> Major ABI versions are declared regularly and are then supported for
>>>>> at least one year, typically aligned with the :ref:`LTS release <stable_lts_releases>`.
>>>>> "
>>>>
>>>> So look, this one was a decision of the technical board.
>>>
>>> The techboard didn't decide to change the ABI every year.
>>> We decided to review the duration after the first year, with a plan to extend.
>>>
>>>> My position is still what was agreed was, "declared every year, and supported for one year".
>>>> I like it, it's crystal clear what is the policy, until we change the policy.
>>>
>>> I think it gives a wrong message.
>>>
>>>> That said, I can make the change no problem, but I need some others to chime in to ok it. 
>>>> Perhaps at the head of the Techboard today?
>>>
>>> Yes I add it to the techboard meeting.
> 
> The techboard propose other rewords:
> "supported" may be replaced with "compatibility is enforced"
> "every year" may be replaced with "no more frequently than every year"
> "declared" may be replaced with "could be declared"
> 
> I think you got the idea. Please adjust wording to something more accurate.
> 
> ###

ACK - done in v9

> 
>>>>>> +A major ABI version is declared every year, aligned with that year's LTS
>>>>>> +release, e.g. v19.11. This ABI version is then supported for one year by all
>>>>>> +subsequent releases within that time period, until the next LTS release, e.g.
>>>>>> +v20.11.
>>>>>
>>>>> Let's reword like this:
>>>>> "
>>>>> A new major ABI version can be declared when a new LTS branch is started,
> 
> It has been suggested to replace "can" with "may".


ACK - I loosened the wording as described above "no more frequently than every year" etc in v9

> 
>>>>> e.g. ABI 19 for DPDK 19.11.0.
>>>>> This major ABI version is then supported until the next one,
>>>>> e.g. ABI 20 for DPDK 20.11.0.
>>>>> All ABI changes must be detailed in the release notes.
>>>>> "
> 
> My reword is wrong because ABI versions should be 20 and 21 respectively.

ACK - fixed

> 
>>>> This is more ambiguous, although what I said above stands.
>>>
>>> What you said is wrong because of 2 reasons:
>>> - it is not always one year for an major ABI
>>
>> Well that is a point of disagreement.
> 
> The techboard agreed to remove "every year".

ACK - loosened the wording. 

>>
>>> - it is always longer because of LTS branch
>>
>> Well I was pretty careful to qualify the ABI policy applies to releases over the year.
>> To distinguish it from LTS branch. 
> 
> As above, we may replace "ABI is supported" with
> "ABI compatibility is enforced".
> 
>>>> If there is general agreement with changing this part of the policy, I am ok to make 
>>>> the change.
>>>
>>> Yes let's review with the techboard.
> 
> Please try to reflect techboard comments while keeping something understandable :)
> 
> ###

ACK - yes, it is readable.

> 
>>>>>> +   ABI breakages due to changes such as reorganizing public
>>>>>> +   structure fields for aesthetic or readability purposes should be avoided.
>>>>>
>>>>> Why it should be avoided?
>>>>> If the ABI is broken anyway, I don't see any reason to not break it more.
>>>>
>>>> This is text from the original ABI Policy - I think the general sentiment still stands.
>>>> Just because you have an ABI Breakage window doesn't mean you should feel free to break
>>>> the ABI. The 3 ACKs required from Technical Board member to change the ABI, are another
>>>> reflection of this. 
>>>>
>>>> As a general rule.
>>>> Unnecessary changes should still be avoided, to reduce ABI churn between ABI versions.
>>>
>>> I agree we must avoid unnecessary API changes because it requires apps to adapt.
>>> But if the change is only ABI, and we are in an ABI-change window,
>>> I don't see any issue
> 
> The techboard agrees that the ABI changes are unlimited but API changes must be avoided.
> It is suggested to replace "ABI" with "API". I think this reword is better:
> "
> API changes such as reorganizing public structure fields
> for aesthetic or readability purposes should be avoided.
> "
> 
> ###

ACK - done

> 
>>>>>> +Libraries marked as ``experimental`` are entirely not considered part of an ABI
>>>>>> +version, and may change without warning at any time. Experimental libraries
>>>>>> +always have a major version of ``0`` to indicate they exist outside of
>>>>>> +ABI Versioning, with the minor version incremented with each ABI change
>>>>>> +to library.
>>>>>
>>>>> It means not all libraries will have the same ABI version.
>>>>> It is contrary of "ABI version is managed at a project level",
>>>>> and I don't see a real benefit of a different version number.
>>>>
>>>> There is a benefit, major version 0 is a very clear indication that 
>>>> the library exists outside of ABI management. 
>>>> A library isn't in the ABI, until it is in the ABI - an then it gets
>>>> added to the major version number. 
>>>>
>>>>> Anyway, some experimental functions can live inside a library
>>>>> with a stable ABI version number
>>>>
>>>> True, but if an entire library is experimental - let's be crystal 
>>>> clear about that. 
>>>
>>> I would like to see what others think.
> 
> The techboard decided to keep this policy: .0 for pure experimental libs.
> 
>