Gentoo Archives: gentoo-dev-announce

From: Fabian Groffen <grobian@g.o>
To: gentoo-project@l.g.o, gentoo-dev-announce@l.g.o
Subject: [gentoo-dev-announce] On eclass APIs
Date: Tue, 27 Dec 2011 20:08:59
Message-Id: 20111227193536.GZ780@gentoo.org
1 In the Council meeting at 20111108, the Council decided that a backwards
2 incompatible API change of an eclass should be announced 30-days in
3 advance:
4
5 "When removing a function or changing the API of an eclass, make
6 sure that it doesn't break any ebuilds in the tree, and post a
7 notice to gentoo-dev at least 30 days in advance, preferably with
8 a patch included."
9 http://www.gentoo.org/proj/en/council/meeting-logs/20111108-summary.txt
10
11 In addition to this, a broader discussion on policies for API changes on
12 eclasses was called for by the Council. This email tries to open up
13 that discussion.
14
15
16 The problem of eclass API changes is similar to API/ABI changes found
17 elsewhere. Since eclasses are intended to have many consumers, changes
18 to them can potentially affect many ebuilds or other eclasses, also
19 outside of Gentoo's main focus (e.g. in overlays).
20
21 Currently, the following API changing eclass practices seem to be in use:
22 - deprecate a function, remove all of its usages, wait, remove the
23 function (or entire eclass)
24 - update a function thereby changing its signature and contract,
25 followed by fixing all usages of said function (now has to be
26 announced to -dev by Council decision)
27 - create a new revision of the eclass to hold changed interfaces,
28 deprecating older revision(s) of the eclass after a long time
29 [are there more types of changes here?]
30
31 One of the ideas is to use revisions in the way libtool applies its
32 rules for shared library versioning (translated to the ELF naming
33 scheme, using three fields major.minor.revision):
34 - no changes, no version changes
35 - changes to the code (bug fixes), but no API changes, increment
36 revision
37 - only backward compatible API changes (new funcs), increment minor,
38 set revision to 0
39 - if there are (also) incompatible API changes (removed funcs,
40 changed arguments), increment major, minor and revision to 0
41
42 Each major increment means an incompatible ABI for the given shared
43 library, the minor and revision denote additions and fixes. We can
44 hence only focus on the major number.
45
46 Changes that are made to eclasses, can hence be reflected as revbumps:
47 - fix functions, or make them smarter without breaking any API (no
48 revbump)
49 - add new functions (no revbump)
50 - drop functions, or change their interface (revbump)
51
52 Doing so will, however, lead to a lot of duplication of functions,
53 since each incompatible change would have to lead to a new revision,
54 that holds all the other functions as well -- unless some smart
55 overloading trick can be applied.
56
57 Is this necessary for just one function, or is this only beneficial
58 after a huge revamp of some eclass? Is it acceptable to take the
59 breakage outside Gentoo, given the extra work imposed by creating
60 revisions and keeping track?
61
62 Any opinions, ideas or alternatives?
63
64
65 --
66 Fabian Groffen
67 Gentoo on a different level

Attachments

File name MIME type
signature.asc application/pgp-signature