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
Lists: gentoo-project: < Prev By Thread Next > < Prev By Date Next >
To: gentoo-project@g.o
From: Ralph Sennhauser <sera@g.o>
Subject: Re: On eclass APIs
Date: Mon, 2 Jan 2012 14:26:59 +0100
On Tue, 27 Dec 2011 20:35:36 +0100
Fabian Groffen <grobian@g.o> 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."
> 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)
> - create a new revision of the eclass to hold changed interfaces,
>   deprecating older revision(s) of the eclass after a long time
> [are there more types of changes here?]
> 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?

Some rules of thumb which pop into mind:

- Never change a public eclass function in a not backward compatible
- A function must be deprecated at least 1 (preferably 3) year(s) before
  it can be removed.
- A deprecated function must emit a deprecation warning on use.
- It's ok for a function to have different behaviour / api based on
  the ebuilds EAPI. So should be done only sporadically for obvious
- If a function needs change beyond what's possible without a not
  backward compatible api change the function needs a new name
  (appending version or whatever).
- Deprecating and removing / replacing a whole eclass can be done
  relatively fast. Consumers of the eclass can grab the eclass from
  attic if they need.
- Eclass names can't be reused. A replacement eclass gets a version
  appended / bumped.
- Internal and public functions / variables must be clearly
- Fixing abusers of internal functions / variables in main tree is
  sufficient for removing or changing the internal api.


On eclass APIs
-- Fabian Groffen
Lists: gentoo-project: < Prev By Thread Next > < Prev By Date Next >
Previous by thread:
Re: On eclass APIs
Next by thread:
let's stop using short gpg key ids, that's insecure
Previous by date:
Re: On eclass APIs
Next by date:
let's stop using short gpg key ids, that's insecure

Updated Jul 05, 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.