[gentoo-dev-announce] On eclass APIs

[gentoo-dev-announce] On eclass APIs

[Fabian Groffen]

[-- Attachment #1: Type: text/plain, Size: 2926 bytes --]

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)
- 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?


-- 
Fabian Groffen
Gentoo on a different level

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 195 bytes --]