| 1 |
On Tue, Dec 27, 2011 at 08:35:36PM +0100, Fabian Groffen wrote: |
| 2 |
> In the Council meeting at 20111108, the Council decided that a backwards |
| 3 |
> incompatible API change of an eclass should be announced 30-days in |
| 4 |
> advance: |
| 5 |
> |
| 6 |
> "When removing a function or changing the API of an eclass, make |
| 7 |
> sure that it doesn't break any ebuilds in the tree, and post a |
| 8 |
> notice to gentoo-dev at least 30 days in advance, preferably with |
| 9 |
> a patch included." |
| 10 |
> http://www.gentoo.org/proj/en/council/meeting-logs/20111108-summary.txt |
| 11 |
> |
| 12 |
> In addition to this, a broader discussion on policies for API changes on |
| 13 |
> eclasses was called for by the Council. This email tries to open up |
| 14 |
> that discussion. |
| 15 |
> |
| 16 |
> |
| 17 |
> The problem of eclass API changes is similar to API/ABI changes found |
| 18 |
> elsewhere. Since eclasses are intended to have many consumers, changes |
| 19 |
> to them can potentially affect many ebuilds or other eclasses, also |
| 20 |
> outside of Gentoo's main focus (e.g. in overlays). |
| 21 |
> |
| 22 |
> Currently, the following API changing eclass practices seem to be in use: |
| 23 |
> - deprecate a function, remove all of its usages, wait, remove the |
| 24 |
> function (or entire eclass) |
| 25 |
> - update a function thereby changing its signature and contract, |
| 26 |
> followed by fixing all usages of said function (now has to be |
| 27 |
> announced to -dev by Council decision) |
| 28 |
|
| 29 |
This breaks overlays unless the API modification is backwards |
| 30 |
compatible; by it's nature, this shouldn't be done since it's a hard |
| 31 |
cut over (overlays have to be updated at the same time, same for |
| 32 |
ebuilds). |
| 33 |
|
| 34 |
Even if you try to fix all gentoo repo ebuilds at the same time, it |
| 35 |
still is possible due to cvs lacking repo-wide atomic commits for part |
| 36 |
of the work to go out. |
| 37 |
|
| 38 |
So... don't do it, at least not with cvs nor if you care about overlay |
| 39 |
consumers. |
| 40 |
|
| 41 |
> One of the ideas is to use revisions in the way libtool applies its |
| 42 |
> rules for shared library versioning (translated to the ELF naming |
| 43 |
> scheme, using three fields major.minor.revision): |
| 44 |
> - no changes, no version changes |
| 45 |
> - changes to the code (bug fixes), but no API changes, increment |
| 46 |
> revision |
| 47 |
> - only backward compatible API changes (new funcs), increment minor, |
| 48 |
> set revision to 0 |
| 49 |
> - if there are (also) incompatible API changes (removed funcs, |
| 50 |
> changed arguments), increment major, minor and revision to 0 |
| 51 |
> |
| 52 |
> Each major increment means an incompatible ABI for the given shared |
| 53 |
> library, the minor and revision denote additions and fixes. We can |
| 54 |
> hence only focus on the major number. |
| 55 |
> |
| 56 |
> Changes that are made to eclasses, can hence be reflected as revbumps: |
| 57 |
> - fix functions, or make them smarter without breaking any API (no |
| 58 |
> revbump) |
| 59 |
> - add new functions (no revbump) |
| 60 |
> - drop functions, or change their interface (revbump) |
| 61 |
> |
| 62 |
> Doing so will, however, lead to a lot of duplication of functions, |
| 63 |
> since each incompatible change would have to lead to a new revision, |
| 64 |
> that holds all the other functions as well -- unless some smart |
| 65 |
> overloading trick can be applied. |
| 66 |
> |
| 67 |
> Is this necessary for just one function, or is this only beneficial |
| 68 |
> after a huge revamp of some eclass? Is it acceptable to take the |
| 69 |
> breakage outside Gentoo, given the extra work imposed by creating |
| 70 |
> revisions and keeping track? |
| 71 |
> |
| 72 |
> Any opinions, ideas or alternatives? |
| 73 |
|
| 74 |
Personal views: generally speaking you can mangle the API as necessary |
| 75 |
w/ the caveat you only change the API in an incompatible way for |
| 76 |
internal functionality (demarked however you'd like- _func_name for |
| 77 |
example). |
| 78 |
|
| 79 |
If you're rewriting the eclass into something sane (python eclass for |
| 80 |
example), than just purely from a stability standpoint... do it in a |
| 81 |
new eclass, and migrate things over. |
| 82 |
|
| 83 |
That said, I don't agree with arbitrary revbumping; one thing to keep |
| 84 |
in mind is that there is *not* an ABI component to eclasses- we have |
| 85 |
env saving. There purely is API, and overlays are the only thing we |
| 86 |
can't update at the same time, so having to revbump eclasses isn't |
| 87 |
worth it- nor is it in anyway friendly for people trying to do a cvs |
| 88 |
log on the eclass to figure out wtf has occured to it. |
| 89 |
|
| 90 |
~brian |
Archives