[dpdk-dev] versioning and maintenance

Thomas Monjalon thomas.monjalon at 6wind.com
Thu Nov 20 22:08:25 CET 2014

2014-11-20 13:25, Neil Horman:
> On Thu, Nov 20, 2014 at 06:09:10PM +0100, Thomas Monjalon wrote:
> > 2014-11-19 10:13, Neil Horman:
> > > On Wed, Nov 19, 2014 at 11:35:08AM +0000, Bruce Richardson wrote:
> > > > On Wed, Nov 19, 2014 at 12:22:14PM +0100, Thomas Monjalon wrote:
> > > > > Following the discussion we had with Neil during the conference call,
> > > > > I suggest this plan, starting with the next release (2.0):
> > > > > 	- add version numbers to libraries
> > > > > 	- add version numbers to functions inside .map files
> > > > > 	- create a git tree dedicated to maintenance and API compatibility
> > > > > 
> > > > > It means these version numbers must be incremented when breaking the API.
> > > > > Though the old code paths will be maintained and tested separately by volunteers.
> > > > > A mailing list for maintenance purpose could be created if needed.
> > > > >
> > > > Hi Thomas,
> > > > 
> > > > I really think that the versionning is best handled inside the main repository
> > > > itself. Given that the proposed deprecation policy is over two releases i.e. an
> > > > API is marked deprecated in release X and then removed in X+1, I don't see the
> > > > maintaining of old code paths to be particularly onerous.
> > > > 
> > > > /Bruce
> > > 
> > > I agree with Bruce, even if it is on occasion an added workload, its not the
> > > sort of thing that can or should be placed on an alternate developer.  Backwards
> > > compatibility is the sort of thing that has to be on the mind of the developer
> > > when modifying an API, and on the mind of the reviewer when reviewing code.  To
> > > shunt that responsibility elsewhere invites the opportunity for backwards
> > > compatibilty to be a second class citizen who's goal will never be reached,
> > > because developers instituting ABI changes will never care about the
> > > consequences, and anyone worrying about backwards compatibility will always be
> > > playing catch up, possibly allowing ABI breaks to slip through.
> > > 
> > > Neil
> >  
> > Before taking a decision, we should detail every concern.
> > 
> > 1/
> > Currently there are not a lot of API refactoring because DPDK is well tailored
> > for x86 and Intel NICs. But we are seeing that new CPU and new NICs to support
> > would require some adaptations.
> > 
> Yes, you're absolutely right here.  I had hoped that, during my presentation
> that this would happen occasionaly, and that we would need to deal with it.
> What I think you are implying here (correct me if I'm wrong), is that you would
> advocate that we wait to introduce ABI versioning until after such refactoring
> is, for lack of a better term "complete".  The problem here is that, software
> that is growing in user base is never "complete".  What you are effectively
> saying is that you want to wait until the API is in a state in which no (or
> almost no) more changes are required, then fixate it.  Thats quite simply never
> going to happen.  And if it does, it obviates the need for versioning at all.

I agree Neil. This point is not about how long we should wait but how the
overhead could be estimate for coming releases.

> > 2/
> > I'm curious to know how you would handle a big change like the recent mbuf rework.
> > Should we duplicate the structure and all the functions using mbuf?
> Several ways, what you suggest above is one way, although thats what I would
> consider to be a pessimal case.  Ideally such large changes are extreemely rare
> (a search of the git history I think confirms this).  Much more common are
> small, limited changes to various API's for which providing multiple versions of
> a function is a much more reasonable approach.
> In the event that we do decide to do a refactor that is so far reaching that we
> simply don't feel like multi-versioning is feasible, the recourse is then to
> deprecate the old API, publish that information on the deprecation schedule,
> wait for a release, then replace it wholesale.  When the API is released, we
> bump the DSO version number.  Note the versioning policy never guarantees that
> backwards compatibility will always be available, nor does it stipulate that a
> newer version of the API is available prior to removing the old one. The goal
> here is to give distributors and application vendors advanced notice of ABI
> breaking changes so that they can adapt appropriately before they are caught off
> guard.  If the new ABI can't be packaged alongside the old, then so be it,
> downstream vendors will have to use the upstream git head to test and validate,
> rather than a newer distribution release

Seems reasonable.

> Ideally though, that shouldn't happen, because it causes downstream headaches,
> and we would really like to avoid that.  Thats why I feel its so important to
> keep this work in the main tree.  If we segregate it to a separate location it
> will make it all to easy for developers to ignore these needs and just assume we
> constantly drop old ABI versions without providing backwards compatibility.
> > 3/
> > Should we add new fields at the end of its structure to avoid ABI breaking?
> > 
> In the common case yes, this usually avoids ABI breakage, though it can't always
> be relied upon (e.g. cases where structures are statically allocated by an
> application).  And then there are patches that attempt to reduce memory usage
> and increase performance by re-arranging structures.  In those cases we need to
> do ABI versioning or announce/delay/release as noted above, though again, that
> should really be avoided if possible.

So there is no hope of having fields logically sorted.
Not a major problem but we have to know it. And it should probably be
documented if we choose this way.

> > 4/
> > Developers contribute because they need some changes. So when breaking
> > an API, their application is already ready for the new version.
> > I mean the author of such patch is probably not really motivated to keep ABI
> > compability and duplicate the code path.
> > 
> What?  That doesn't make any sense.  Its our job to enforce this requirement on
> developers during the review cycle.  If you don't feel like we can enforce
> coding requirements on the project, we've already lost.  I agree that an
> application developer submitting a patch for DPDK might not care about ABI
> compatibility because they've already modified their application, but they (and
> we) need to recognize that there are more than just a handful of users of the
> DPDK, some of whom don't participate in this community (i.e. are simply end
> users).  We need to make sure all users needs are met.  Thats the entire point
> of this patch series, to make DPDK available to a wider range of users.

Exact. To make it simple, you care about end users and I have to care about
developers motivation. But I perfectly understand the end users needs.
I don't say we cannot enforce coding requirements. I just think it will be
less pleasant.

> > 5/
> > Intead of simply modifying an API function, it would appear as a whole new
> > function with some differences compared to the old one. Such change is really
> > not convenient to review.
> Um, yes, versioning is the process of creating an additional
> function that closely resembles an older version of the same function, but with
> different arguments and a newer version number.  Thats what it is by defintion,
> and yes, its additional work.  All you're saying here is that, its extra work
> and we shouldn't do it.  I thought I made this clear on the call, its been done
> in thousands of other libraries, but if you just don't want to do it, then you
> should abandon distributions as a way to reach a larger community, but if you
> want to see the DPDK reach a larger community, then this is something that has
> to happen, hard or not.

The goal of this discussion is to establish all the implications of this
decision. We expose the facts. No conclusion.

> > 6/
> > Testing ABI compatibility could be tricky. We would need a tool to check it's
> > mostly OK. The good place for such a tool is in app/test. It was designed to be
> > the unit tests of the API.
> That seems like a reasonable idea, but I'm not sure what the concern is.  Are
> you saying that you need to test every old version of the ABI?  Thats fine.  I
> really don't think it has to be as stringent as the latest version testing, but
> if you want to, it should be as easy as building the latest release of
> the DPDK libraries, and the previous version of the test application.  That will
> force the previous version code paths to be used by the test app in the new
> library and, if the test fully exercize the api, then you should get pretty good
> coverage.

Yes it will provide an unit test to developpers.

> > 7/
> > This system would allow application developpers to upgrade DPDK to n+1 without
> > rebuilding. But when upgrading to n+2, they should have adapted their
> > application to comply with n+1 API (because n will be removed).
> Only assuming that the old ABI facet was deprecated at the same time the new ABI
> was introduced.  Theres nothing that says we have to do that, but I digress.
> > So this solution offers a delay between the upgrade decision and the
> > app work. Note that they could prepare their application before upgrading.
> > Anyway, an upgrade should be tested before doing it effectively. The behaviour
> > of the application could change and require some adaptations.
> > 
> Um, yes.  Whats the concern here?

I'm just trying to figure which workflows are eased by progressive ABI deprecation.

> Downstream application developers need 2
> things:
> A) The ability to note that ABI changes are comming so that they can adapt to
> the new version
> B) Time to do so
> The deprecation policy, if properly distributed by Distributions provide (A),
> and the ABI versioning provides (B).  I.e. they can get all the latest bug fixes
> and enhancements while in parallel adapting to the comming new version. Note
> ideally this will happen rarely, as having to constantly rebuild/adapt does not
> sit will with application vendors who choose to go through distributions, but
> we'll do the best we can.

It's an interesting point. In a long-term distribution model like RHEL, do you
plan to upgrade DPDK at each new release?

> > 8/
> > How to handle a change in the implementation of a PMD which severely impact
> > the application? Example: an ol_flag was mis-used and the application has
> > a workaround to interpret this flag but it's now incompatible with the fix.
> > 
> We run into this sometimes in Fedora and RHEL, and doesn't require versioning.
> The problem you describe is one in which something internal to the library that
> an application has come to rely on.  Fixing the bug isn't typically considered
> within the purview of versioning, because you're not changing the ABI, you're
> just correcting a bug in the PMD's behavior.  Customers who ask for the behavior
> to remain unchanged are asking for what's commonly referred to as "Bug for Bug
> compatibility" and in those cases the application vendor needs to release a
> corresponding fix.  Developers can't be required to preserve buggy behavior.
> It should also be noted that in this case, ABI never changed.  All the data
> types/sizes/locations/etc have remained unchanged. Its just a bug in
> interpretation of data passed accross the ABI. As such, theres nothing for ABI
> versioning to do here.

OK, that's what I thought.

> > 9/
> > When we don't want to adapt an application, it means the development is
> > finished and we don't care about the new features of the library.
> > So I wonder if it wouldn't be more appropriate to provide stable releases
> > with true maintenance to such users. I understood that is what Redhat provides
> > to their customers.
> > 
> No, thats incorrect, we frequently update packages to the latest upstream
> version when at all possible.  We are able to do this sepcifically because
> upstream library releases provide ABI versioning, so that we can update with
> confidence.  If they don't do that, then yes, we are often restricted to
> selecting a release and maintaining it for the duration of a major RHEL release,
> which implies that security and feature updates are extreemely limited
> That said, if you wanted to do ongoing maintenence on each release, I suppsose
> you could, in fact its somewhat simmilar to the -stable series that the kernel
> uses, exept that the kernel enoys an extreemly stable user space ABI, and even
> then the kernel -stable series doesn't take internal ABI changing patches, so
> theres alot of divergence.  You don't currently have that stable ABI interface,
> and so I think you'll find that that doing this is way more work than just
> supporting versioning.
> To illustrate, lets say you want to support maintenence releases the latest 3
> releases of the DPDK with patches.  To do this, for every patch that is posted
> to the dpdk that is a bug fix, you will have to apply it four times, one for
> the git head, and again for each of the three releases that you are doing
> maintenence on.  the patch will of course apply cleanly to the git head, as
> thats what the developer wrote it against, but the other three releases have
> every opportunity to conflict with code introduced in the git head but that
> couldn't be taken into the maintenece releases.  Fixing those up is work that
> you will either have to do, or request that the patch author do.  And for this
> work you will provide distibutions with about 2 years of ABI stability
> (presuming an ~8 month release cycle), after which they are back to just living
> with whatever they stabilized on until the next major relase (note a single RHEL
> major release has a 10+ year life cycle).  I would personally rather avoid that
> work, and just do the ABI compatibility, as those patches are far fewer in
> number, and it buys for the effort.

Interesting point of view.
Note that there is no plan to maintain stable version on dpdk.org.
But if some volunteers want absolutely to do it (even after reading your comment),
we cannot forbid it.

> > Hope this discussion will bring a clear idea of what should be done with
> > which implications.
> > Thanks
Thanks again

More information about the dev mailing list