From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from pigeon.gentoo.org ([208.92.234.80] helo=lists.gentoo.org) by finch.gentoo.org with esmtp (Exim 4.60) (envelope-from ) id 1Rhi1X-0007yC-MO for garchives@archives.gentoo.org; Mon, 02 Jan 2012 13:34:00 +0000 Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 6773A21C171; Mon, 2 Jan 2012 13:33:24 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) by pigeon.gentoo.org (Postfix) with ESMTP id 9727821C1B5 for ; Mon, 2 Jan 2012 13:33:05 +0000 (UTC) Received: from sera-17.lan (224-12.203-62.cust.bluewin.ch [62.203.12.224]) (using TLSv1 with cipher DHE-RSA-AES128-SHA (128/128 bits)) (No client certificate requested) (Authenticated sender: sera) by smtp.gentoo.org (Postfix) with ESMTPSA id 4198E1B4010 for ; Mon, 2 Jan 2012 13:33:04 +0000 (UTC) Date: Mon, 2 Jan 2012 14:26:59 +0100 From: Ralph Sennhauser To: gentoo-project@lists.gentoo.org Subject: Re: [gentoo-project] On eclass APIs Message-ID: <20120102142659.0e5420a6@sera-17.lan> In-Reply-To: <20111227193536.GZ780@gentoo.org> References: <20111227193536.GZ780@gentoo.org> Organization: Gentoo Linux X-Mailer: Claws Mail 3.7.10 (GTK+ 2.24.5; x86_64-pc-linux-gnu) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Project discussion list X-BeenThere: gentoo-project@lists.gentoo.org Reply-To: gentoo-project@lists.gentoo.org Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-Archives-Salt: 30f7f915-d690-49d4-a569-23db0a58e8d9 X-Archives-Hash: 1b4e94926fde84f7c1ff5e43705b89e4 On Tue, 27 Dec 2011 20:35:36 +0100 Fabian Groffen wrote: > 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? > > Some rules of thumb which pop into mind: - Never change a public eclass function in a not backward compatible fashion. - A function must be deprecated at least 1 (preferably 3) year(s) before it can be removed. - A deprecated function must emit a deprecation warning on use. - It's ok for a function to have different behaviour / api based on the ebuilds EAPI. So should be done only sporadically for obvious reasons. - If a function needs change beyond what's possible without a not backward compatible api change the function needs a new name (appending version or whatever). - Deprecating and removing / replacing a whole eclass can be done relatively fast. Consumers of the eclass can grab the eclass from attic if they need. - Eclass names can't be reused. A replacement eclass gets a version appended / bumped. - Internal and public functions / variables must be clearly distinguishable. - Fixing abusers of internal functions / variables in main tree is sufficient for removing or changing the internal api. Cheers, sera