[dpdk-dev] How to manage new APIs added after major ABI release?

[Bruce Richardson]

On Wed, Dec 11, 2019 at 04:02:16PM +0100, Thomas Monjalon wrote:
> 11/12/2019 14:30, Ferruh Yigit:
> > On 12/11/2019 1:11 PM, Neil Horman wrote:
> > > On Tue, Dec 10, 2019 at 11:56:28AM +0000, Ferruh Yigit wrote:
> > >> Hi,
> > >>
> > >> With new process, the major ABI releases will be compatible until it is
> > >> deprecated (until next LTS for now),
> > >> like current ABI version is 20 in DPDK_19.11 and DPDK versions until DPDK_20.11
> > >> will be ABI compatible with this version.
> > >>
> > >> But if we introduce a new API after major ABI, say in 20.02 release, are we
> > >> allowed to break the ABI for that API before DPDK_20.11?
> > >>
> > >> If we allow it break, following problem will be observed:
> > >> Assume an application using .so.20.1 library, and using the new API introduced
> > >> in 20.02, lets say foo(),
> > >> but when application switches to .so.20.2 (released via DPDK_20.05), application
> > >> will fail because of ABI breakage in foo().
> > >>
> > >> I think it is fair that application expects forward compatibility in minor
> > >> versions of a shared library.
> > >> Like if application linked against .so.20.2, fair to expect .so.20.3, .so.20.4
> > >> etc will work fine. I think currently only .so.20.0 is fully forward compatible.
> > >>
> > >> If we all agree on this, we may need to tweak the process a little, but before
> > >> diving into implementation details, I would like to be sure we are in same page.
> > >>
> > > Yes, I agree with the assertion.  Once an ABI is fixed, it must be compatible
> > > with all future minor releases subsequent to the fixing of that ABI, until the
> > > next major update.  That is to say, once you release ABI_20, all minor updates
> > > 20.01, 20.02, etc must be compatible with ABI_20 until such time as ABI_21 is
> > > released.
> > 
> > There is a slight difference. All minor versions already compatible with ABI_20,
> > like: 20.01, 20.02, 20.03 are ABI compatible with 20.0 (which defines ABI_20).
> > 
> > Question is if 20.03 should be compatible with 20.02?
> > 
> > This can happen if a new API is introduced in 20.2 and ABI has broken for that
> > API in 20.3, so an ABI compatibility issue created between 20.03 & 20.02,
> > meanwhile both are compatible with ABI_20.
> > 
> > I can see two options:
> > a) New APIs are introduced only when we switch to new major ABI version. But if
> > we switch to longer (2 years) ABI compatibility, I think this is unacceptable to
> > wait up to two years to have (non experimental) APIs.
> 
> I agree we should allow to add a new stable API in the middle of an ABI lifecycle.
> 
> > b) APIs added in minor version will be part of ABI_20 after that point and same
> > rules will apply to them. Like if and API has introduced in 20.2, it is not
> > allowed to be broken until next major ABI version.
> 
> Yes I think it is compliant with the agreed policy.
> Note that an app linked with ABI 20.2 won't be compatible with ABI 20.1,
> though the reverse works.
>
Which I think is fine, as it is the way most people would expect it to
work.