1 |
On Tue, 27 Dec 2011 20:35:36 +0100 |
2 |
Fabian Groffen <grobian@g.o> wrote: |
3 |
|
4 |
> In the Council meeting at 20111108, the Council decided that a |
5 |
> backwards incompatible API change of an eclass should be announced |
6 |
> 30-days in advance: |
7 |
> |
8 |
> "When removing a function or changing the API of an eclass, make |
9 |
> sure that it doesn't break any ebuilds in the tree, and post a |
10 |
> notice to gentoo-dev at least 30 days in advance, preferably with |
11 |
> a patch included." |
12 |
> http://www.gentoo.org/proj/en/council/meeting-logs/20111108-summary.txt |
13 |
> |
14 |
> In addition to this, a broader discussion on policies for API changes |
15 |
> on eclasses was called for by the Council. This email tries to open |
16 |
> up that discussion. |
17 |
> |
18 |
> |
19 |
> The problem of eclass API changes is similar to API/ABI changes found |
20 |
> elsewhere. Since eclasses are intended to have many consumers, |
21 |
> changes to them can potentially affect many ebuilds or other |
22 |
> eclasses, also outside of Gentoo's main focus (e.g. in overlays). |
23 |
> |
24 |
> Currently, the following API changing eclass practices seem to be in |
25 |
> use: |
26 |
> - deprecate a function, remove all of its usages, wait, remove the |
27 |
> function (or entire eclass) |
28 |
> - update a function thereby changing its signature and contract, |
29 |
> followed by fixing all usages of said function (now has to be |
30 |
> announced to -dev by Council decision) |
31 |
> - create a new revision of the eclass to hold changed interfaces, |
32 |
> deprecating older revision(s) of the eclass after a long time |
33 |
> [are there more types of changes here?] |
34 |
> |
35 |
> One of the ideas is to use revisions in the way libtool applies its |
36 |
> rules for shared library versioning (translated to the ELF naming |
37 |
> scheme, using three fields major.minor.revision): |
38 |
> - no changes, no version changes |
39 |
> - changes to the code (bug fixes), but no API changes, increment |
40 |
> revision |
41 |
> - only backward compatible API changes (new funcs), increment minor, |
42 |
> set revision to 0 |
43 |
> - if there are (also) incompatible API changes (removed funcs, |
44 |
> changed arguments), increment major, minor and revision to 0 |
45 |
> |
46 |
> Each major increment means an incompatible ABI for the given shared |
47 |
> library, the minor and revision denote additions and fixes. We can |
48 |
> hence only focus on the major number. |
49 |
> |
50 |
> Changes that are made to eclasses, can hence be reflected as revbumps: |
51 |
> - fix functions, or make them smarter without breaking any API (no |
52 |
> revbump) |
53 |
> - add new functions (no revbump) |
54 |
> - drop functions, or change their interface (revbump) |
55 |
> |
56 |
> Doing so will, however, lead to a lot of duplication of functions, |
57 |
> since each incompatible change would have to lead to a new revision, |
58 |
> that holds all the other functions as well -- unless some smart |
59 |
> overloading trick can be applied. |
60 |
> |
61 |
> Is this necessary for just one function, or is this only beneficial |
62 |
> after a huge revamp of some eclass? Is it acceptable to take the |
63 |
> breakage outside Gentoo, given the extra work imposed by creating |
64 |
> revisions and keeping track? |
65 |
> |
66 |
> Any opinions, ideas or alternatives? |
67 |
> |
68 |
> |
69 |
|
70 |
Some rules of thumb which pop into mind: |
71 |
|
72 |
- Never change a public eclass function in a not backward compatible |
73 |
fashion. |
74 |
- A function must be deprecated at least 1 (preferably 3) year(s) before |
75 |
it can be removed. |
76 |
- A deprecated function must emit a deprecation warning on use. |
77 |
- It's ok for a function to have different behaviour / api based on |
78 |
the ebuilds EAPI. So should be done only sporadically for obvious |
79 |
reasons. |
80 |
- If a function needs change beyond what's possible without a not |
81 |
backward compatible api change the function needs a new name |
82 |
(appending version or whatever). |
83 |
- Deprecating and removing / replacing a whole eclass can be done |
84 |
relatively fast. Consumers of the eclass can grab the eclass from |
85 |
attic if they need. |
86 |
- Eclass names can't be reused. A replacement eclass gets a version |
87 |
appended / bumped. |
88 |
- Internal and public functions / variables must be clearly |
89 |
distinguishable. |
90 |
- Fixing abusers of internal functions / variables in main tree is |
91 |
sufficient for removing or changing the internal api. |
92 |
|
93 |
Cheers, |
94 |
sera |