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 |