Title:Gentoo Stable Portage Tree
Last-Modified:2004/11/02 15:38:58
Author:Kurt Lieber <klieber at>
Type:Standards Track
Post-History:29-Jan-2004 2-Nov-2004



This GLEP is intended to propose a series of changes to the Portage tree that are necessary to facilitate the use of Gentoo in areas where stability and predictability are of paramount importance, including servers in enterprise environments, mission critical workstations and other such installations.

The proposed solution involves creating a separate tree in Portage that is updated far less often than the regular tree. Outside of periodic updates, this tree would only be updated with critical bugfixes and security patches.


Currently recruiting people who would be willing to help with this GLEP.


Enterprise users typically value stability and a predictable upgrade path over having the latest packages or features available to them. Historically, Gentoo Linux has been unable to provide such an environment due to the dynamic nature of the Portage tree.


The Gentoo Infrastructure team will need to provide an additional Portage tree on our rsync mirroring system. This new tree will house the ebuilds associated with the stable tree. It also impacts all Gentoo developers responsible for creating and updating ebuilds as they will be expected to integrate the tagging of ebuilds for the stable tree into their normal development process, both for the quarterly release cycles as well as off-cycle bug and security fixes.

The Gentoo Documentation team will also be affected as they will be responsible for updating installation documents to take these new features into account.


A basic outline of various ways of adding a "stable" tree to Portage was discussed in the gentoo managers meeting on 26-Jan-04. Consensus seemed to be reached that such a solution was needed and that branching the gentoo-x86 repository was the appropriate way to accomplish this. The largest area of disagreement surrounded how specific ebuilds should be targeted for inclusion in the stable tree.

One suggested solution was a simple branch of the CVS tree and having developers work in two separate branches; one for the stable tree and another for the traditional tree. However, it was felt this would prove too cumbersome in practice.

Another suggestion was to have a small group of dedicated gentoo-server developers responsible for generating the contents of the stable tree, which would provide more control and quality assurance over the ebuilds added to the stable tree. While this might prove effective for a small number of ebuilds, it is quite likely that this model would not scale enough to allow for a large number of ebuilds in the stable tree and, over time, the project would become resource constrained and unable to meed future deadlines.

The suggestion that seemed to get the most traction was the creation of a new "stable" keyword which would be added to appropriate ebuilds. The use of "stable" would signify ebuilds that are ready for production in the stable tree while "~stable" would be reserved for ebuilds which may be appropriate for the stable tree, but may require further testing before being deemed "ready for production". Off-cycle bug fixes and/or security updates may be examples of ebuilds that require the ~stable tag.


While a 'stable' keyword was originally proposed, after further review, it was determined this offered no way to allow arch-specific stable ebuilds. As such, this GLEP proposes the use of 'stable:<arch>' and '~stable:<arch>' (stable:x86, stable:ppc, etc.)

A new, stable tree will be created by scanning for the 'stable:<arch>' and '~stable:<arch>' keywords in the ebuilds and pulling those ebuilds and associated files into a separate branch of CVS. The stable tree should have the following features:

As mentioned above, the "stable" tree will be updated quarterly, ideally in unison with the release schedule of the main Gentoo branch. This tree will be untouched outside of this update schedule except in the following cases:

In both cases, the maintainer of the package will be responsible for ensuring these patches are properly committed to the stable tree out of cycle.

Backwards Compatibility

All features proposed here are new additions to existing processes and features. There should be no impact on existing features and functionality.