Gentoo Logo
Gentoo Spaceship




Note: Due to technical difficulties, the Archives are currently not up to date. GMANE provides an alternative service for most mailing lists.
c.f. bug 424647
List Archive: gentoo-project
Navigation:
Lists: gentoo-project: < Prev By Thread Next > < Prev By Date Next >
Headers:
To: gentoo-project@g.o
From: Brian Harring <ferringb@...>
Subject: Re: On eclass APIs
Date: Tue, 27 Dec 2011 11:57:31 -0800
On Tue, Dec 27, 2011 at 08:35:36PM +0100, Fabian Groffen wrote:
> In the Council meeting at 20111108, the Council decided that a backwards
> incompatible API change of an eclass should be announced 30-days in
> advance:
> 
>    "When removing a function or changing the API of an eclass, make
>    sure that it doesn't break any ebuilds in the tree, and post a
>    notice to gentoo-dev at least 30 days in advance, preferably with
>    a patch included."
>    http://www.gentoo.org/proj/en/council/meeting-logs/20111108-summary.txt
> 
> In addition to this, a broader discussion on policies for API changes on
> eclasses was called for by the Council.  This email tries to open up
> that discussion.
> 
> 
> The problem of eclass API changes is similar to API/ABI changes found
> elsewhere.  Since eclasses are intended to have many consumers, changes
> to them can potentially affect many ebuilds or other eclasses, also
> outside of Gentoo's main focus (e.g. in overlays).
> 
> Currently, the following API changing eclass practices seem to be in use:
> - deprecate a function, remove all of its usages, wait, remove the
>   function (or entire eclass)
> - update a function thereby changing its signature and contract,
>   followed by fixing all usages of said function (now has to be
>   announced to -dev by Council decision)

This breaks overlays unless the API modification is backwards 
compatible; by it's nature, this shouldn't be done since it's a hard 
cut over (overlays have to be updated at the same time, same for 
ebuilds).

Even if you try to fix all gentoo repo ebuilds at the same time, it 
still is possible due to cvs lacking repo-wide atomic commits for part 
of the work to go out.

So... don't do it, at least not with cvs nor if you care about overlay 
consumers.

> One of the ideas is to use revisions in the way libtool applies its
> rules for shared library versioning (translated to the ELF naming
> scheme, using three fields major.minor.revision):
> - no changes, no version changes
> - changes to the code (bug fixes), but no API changes, increment
>   revision
> - only backward compatible API changes (new funcs), increment minor,
>   set revision to 0
> - if there are (also) incompatible API changes (removed funcs,
>   changed arguments), increment major, minor and revision to 0
> 
> Each major increment means an incompatible ABI for the given shared
> library, the minor and revision denote additions and fixes.  We can
> hence only focus on the major number.
> 
> Changes that are made to eclasses, can hence be reflected as revbumps:
> - fix functions, or make them smarter without breaking any API (no
>   revbump)
> - add new functions (no revbump)
> - drop functions, or change their interface (revbump)
> 
> Doing so will, however, lead to a lot of duplication of functions,
> since each incompatible change would have to lead to a new revision,
> that holds all the other functions as well -- unless some smart
> overloading trick can be applied.
> 
> Is this necessary for just one function, or is this only beneficial
> after a huge revamp of some eclass?  Is it acceptable to take the
> breakage outside Gentoo, given the extra work imposed by creating
> revisions and keeping track?
> 
> Any opinions, ideas or alternatives?

Personal views: generally speaking you can mangle the API as necessary 
w/ the caveat you only change the API in an incompatible way for 
internal functionality (demarked however you'd like- _func_name for 
example).

If you're rewriting the eclass into something sane (python eclass for 
example), than just purely from a stability standpoint... do it in a 
new eclass, and migrate things over.

That said, I don't agree with arbitrary revbumping; one thing to keep 
in mind is that there is *not* an ABI component to eclasses- we have 
env saving.  There purely is API, and overlays are the only thing we 
can't update at the same time, so having to revbump eclasses isn't 
worth it- nor is it in anyway friendly for people trying to do a cvs 
log on the eclass to figure out wtf has occured to it.

~brian


References:
On eclass APIs
-- Fabian Groffen
Navigation:
Lists: gentoo-project: < Prev By Thread Next > < Prev By Date Next >
Previous by thread:
On eclass APIs
Next by thread:
Re: On eclass APIs
Previous by date:
On eclass APIs
Next by date:
Re: On eclass APIs


Updated Jun 18, 2012

Summary: Archive of the gentoo-project mailing list.

Donate to support our development efforts.

Copyright 2001-2013 Gentoo Foundation, Inc. Questions, Comments? Contact us.