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

[Thomas Monjalon <thomas@monjalon.net>]

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 ABI version is managed at a project level in DPDK, with the ABI version
> >> +   reflected in all library's soname.
> > 
> > Yes, even the experimental libraries should have the same version,
> > with the minor number incremented at each release.
> > (just a comment to change a policy at the end of this patch)
> 
> It's described elsewhere in the document, experimental libraries have a major 
> ABI version of 0, to indicate they exist outside of ABI management.
> Minor number then changes as the experimental library changes as before.

Yes, but you cannot say "reflected in all library's soname".

> >> +   In 2019, the DPDK community stated its intention to move to ABI stable
> >> +   releases, over a number of release cycles. This change begins with
> >> +   maintaining ABI stability through one year of DPDK releases starting from
> >> +   DPDK 19.11. This policy will be reviewed in 2020, with intention of
> >> +   lengthening the stability period.
> > 
> > Great, the schedule is clear here.
> > 
> >> +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,
> > 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.
> > "
> 
> 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
- it is always longer because of LTS branch

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

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

> >> +#. ABI breaking changes (including an alternative map file) can be included with
> >> +   deprecation notice, in wrapped way by the ``RTE_NEXT_ABI`` option, to provide
> >> +   more details about oncoming changes. ``RTE_NEXT_ABI`` wrapper will be removed
> >> +   at the declaration of the next major ABI version.
> > 
> > I missed that in discussions.
> > I thought we wanted to wait for the next major ABI.
> > If we allow NEXT_ABI ifdef, we will have 2 DPDK versions
> > (stable and next ABI) to test.
> 
> This is text from the original ABI Policy - the purpose remains the same.
> If you add an ABI breaking change in say 20.02, that clearly can't see the light of day until 20.11
> 
> You may still opt to prepare the community for the change, by putting your code out wrapped 
> in a NEXT_ABI and flagging it. You then get the option for people, so inclined, to build and try your code.
> 
> I can't see it being used often, but it is another tool in the box of managing ABI change.

OK, let's keep this tool.

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