en/glep/glep-0040.txt

GLEP: 40
Title: Standardizing "arch" keywording across all archs.
Version: $Revision: 1.3 $
Last-Modified: $Date: 2005/11/13 17:16:50 $
Author: Grant Goodyear <g2boojum@gentoo.org>
Status: Final
Type: Standards Track
Content-Type: text/x-rst
Created: 3-Sep-2005
Post-History: 6-Sep-2005 15-Sep-2005 3-Sep-2006

Status
======

Approved by the Gentoo Council on 15 September 2005.  As of 20060903
we have a robust x86 arch team, so this GLEP is final

Credits
=======

This GLEP originated from a rather contentious discussion_ on gentoo-dev
about combining the x86 and amd64 keywords.  This GLEP attempts to get at the
heart of that discontent.  The proposed stable-keyword guidelines have been
lifted verbatim from `The Doc`_.

.. _discussion: http://tinyurl.com/bp859
.. _The Doc: http://dev.gentoo.org/~plasmaroo/devmanual

Abstract
========

It is time for x86 to no longer be an exception to the standard
keywording guidelines.  Thus, an x86 arch team should be responsible 
for moving packages from ~x86 to x86.

Motivation
==========

The original, informal x86 keywording policy, where almost any x86 dev (which
were the vast majority of devs) who used a package could mark it stable, arose
from a time when there were relatively few Gentoo devs.  Adding packages to
the tree was the principal concern, as opposed to maintaining existing
packages. QA considerations have since modified that policy slightly, and now
it is the package maintainers who should mark an x86 package stable.  Of
course, that policy presumes that package maintainers are generally x86 devs,
which is slowly becoming less and less true.

This policy for x86 is quite different from how every other arch marks
packages stable.  For the non-x86 archs, each arch has a specific "arch team"
which is responsible for moving packages from ``~arch`` to ``arch``, although
vapier notes that "arch teams generally defer to maintainers (and rightly so)
as to *when* newer versions should go stable."  This approach has worked quite
well for the non-x86 archs, and this GLEP asserts that the same approach would
benefit x86 as well.

Specification
=============

Stabling guidelines for all archs
---------------------------------

For a package to move to stable, the following guidelines must be met:

*  The package has spent a reasonable amount of time in ``~arch`` first.
   Thirty days is the usual figure, although this is clearly only a guideline.
   For critical packages, a much longer duration is expected.  For small
   packages which have only minor changes between versions, a shorter period
   is sometimes appropriate.
*  The package must not have any non-``arch`` dependencies.
*  The package must not have any severe outstanding bugs or issues.
*  The package must be widely tested.
*  If the package is a library, it should be known not to break any package
   which depends upon it.
*  The relevant ``arch`` team must agree to it.

x86 arch team
-------------

A robust x86 arch team needs to be created.  The x86@gentoo.org alias already
exists, and it merely needs to be used.  This team, with the aid of potential
non-dev ``arch testers``, has the responsibility of stabling all x86 packages.
Current x86 devs who wish to mark their own packages stable must therefore
either be members of or make individual arrangements with the x86 arch team.


Rationale
=========

There will be a considerable one-time cost involved in establishing a robust
x86 arch team--a good number of bodies (the amd64 arch team has 19 active devs
and 12 active non-dev arch testers) need to be recruited to be part of the
new arch team, and convincing devs that it is in their best interests to work
in a new fashion is likely to be even harder.  Certainly the benefit of
consistency between the various archs is obvious, but is it worth the cost
involved?  Here are the arguments for enduring the pain involved:

*  Over time, x86 is likely to become a minority arch as 64-bit systems
   become the norm.  The implicit assumptions that underly the current
   system (that most devs, users, and package maintainers use x86)
   will become increasingly less valid.
*  Markedly improved QA for x86.  Assuming that the author's own  is
   behavior is representative, most x86 devs run ``~x86`` systems. 
   Thus, the assumption that devs are good ``x86`` testers is not really
   valid.  One obvious consequence is that packages tend to languish in
   ``~x86`` for a very long time, since x86 devs running ``~x86`` have little
   cause to notice that a package has not been marked stable.  The much larger
   effect, though, is that it is rare for ``x86`` packages to be stabled in
   the context of a full ``x86`` tree, so the big picture of a stable
   *system*, not just a stable package, is lost.  This approach of stabling
   in the context of a full stable ``arch`` tree, it has been argued_, is
   the fundamental reason why the non-x86 archs have notably better QA
   than does the x86 arch.

.. _argued: http://thread.gmane.org/gmane.linux.gentoo.devel/30369

Implementation
==============

Creation of a robust x86 team is already underway.  The more vital step 
is the official change in policy, along with a sustained effort to get
existing x86 devs to go along with it.

Alternative Ideas
=================

Stuart_ has suggested the creation of a new arch keyword: "[-]maint", which 
would exist in tandem with the normal arch keywords, thereby making the
package maintainer's intention explicit.  Ciaranm has responded that by
definition a package in ``~arch`` is a candidate for ``arch``, so a package's
mere presence in the tree (without being in ``package.mask``) should indicate
the package maintainer's intention.  There was a fair bit of discussion about
whether the idea should be a "maint" keyword, or named something else, or an
entirely different variable, etcetera, but the basic gist didn't change much.

Jstubbs notes that it could be a very good idea if all non-arch devs worked in
overlays, but that new portage (gensync) support would be needed to make it
truly viable.  Stuart pointed out that php5 support was handled just that way.
One author's view is that this approach would make the "package in ``~arch``
means that it's a de-facto candidate for ``arch``" interpretation even more 
valid.

Ciaranm and weeve have noted that it is occasionally necessary for arch teams
to override a package maintainer when it comes to stabling a package.  Stuart
has asserted that in those cases the arch team should be willing to take on
the support burden for that package.

.. _Stuart: http://thread.gmane.org/gmane.linux.gentoo.devel/31060

Backwards Compatibility
=======================

Not really an issue here.


Copyright
=========

This document has been placed in the public domain.
1	g2boojum	1.1	GLEP: 40
2			Title: Standardizing "arch" keywording across all archs.
3	g2boojum	1.4	Version: $Revision: 1.3 $
4			Last-Modified: $Date: 2005/11/13 17:16:50 $
5	g2boojum	1.1	Author: Grant Goodyear <g2boojum@gentoo.org>
6	g2boojum	1.4	Status: Final
7	g2boojum	1.1	Type: Standards Track
8			Content-Type: text/x-rst
9			Created: 3-Sep-2005
10	g2boojum	1.4	Post-History: 6-Sep-2005 15-Sep-2005 3-Sep-2006
11	g2boojum	1.2
12			Status
13			======
14
15	g2boojum	1.4	Approved by the Gentoo Council on 15 September 2005. As of 20060903
16			we have a robust x86 arch team, so this GLEP is final
17	g2boojum	1.1
18			Credits
19			=======
20
21			This GLEP originated from a rather contentious discussion_ on gentoo-dev
22			about combining the x86 and amd64 keywords. This GLEP attempts to get at the
23			heart of that discontent. The proposed stable-keyword guidelines have been
24			lifted verbatim from `The Doc`_.
25
26			.. _discussion: http://tinyurl.com/bp859
27			.. _The Doc: http://dev.gentoo.org/~plasmaroo/devmanual
28
29			Abstract
30			========
31
32			It is time for x86 to no longer be an exception to the standard
33			keywording guidelines. Thus, an x86 arch team should be responsible
34			for moving packages from ~x86 to x86.
35
36			Motivation
37			==========
38
39			The original, informal x86 keywording policy, where almost any x86 dev (which
40			were the vast majority of devs) who used a package could mark it stable, arose
41			from a time when there were relatively few Gentoo devs. Adding packages to
42			the tree was the principal concern, as opposed to maintaining existing
43			packages. QA considerations have since modified that policy slightly, and now
44			it is the package maintainers who should mark an x86 package stable. Of
45			course, that policy presumes that package maintainers are generally x86 devs,
46			which is slowly becoming less and less true.
47
48			This policy for x86 is quite different from how every other arch marks
49			packages stable. For the non-x86 archs, each arch has a specific "arch team"
50			which is responsible for moving packages from ``~arch`` to ``arch``, although
51			vapier notes that "arch teams generally defer to maintainers (and rightly so)
52			as to when newer versions should go stable." This approach has worked quite
53			well for the non-x86 archs, and this GLEP asserts that the same approach would
54			benefit x86 as well.
55
56			Specification
57			=============
58
59			Stabling guidelines for all archs
60			---------------------------------
61
62			For a package to move to stable, the following guidelines must be met:
63
64			* The package has spent a reasonable amount of time in ``~arch`` first.
65			Thirty days is the usual figure, although this is clearly only a guideline.
66			For critical packages, a much longer duration is expected. For small
67			packages which have only minor changes between versions, a shorter period
68			is sometimes appropriate.
69			* The package must not have any non-``arch`` dependencies.
70			* The package must not have any severe outstanding bugs or issues.
71			* The package must be widely tested.
72			* If the package is a library, it should be known not to break any package
73			which depends upon it.
74			* The relevant ``arch`` team must agree to it.
75
76			x86 arch team
77			-------------
78
79			A robust x86 arch team needs to be created. The x86@gentoo.org alias already
80			exists, and it merely needs to be used. This team, with the aid of potential
81			non-dev ``arch testers``, has the responsibility of stabling all x86 packages.
82			Current x86 devs who wish to mark their own packages stable must therefore
83			either be members of or make individual arrangements with the x86 arch team.
84
85
86			Rationale
87			=========
88
89			There will be a considerable one-time cost involved in establishing a robust
90	g2boojum	1.3	x86 arch team--a good number of bodies (the amd64 arch team has 19 active devs
91	g2boojum	1.1	and 12 active non-dev arch testers) need to be recruited to be part of the
92			new arch team, and convincing devs that it is in their best interests to work
93			in a new fashion is likely to be even harder. Certainly the benefit of
94			consistency between the various archs is obvious, but is it worth the cost
95			involved? Here are the arguments for enduring the pain involved:
96
97			* Over time, x86 is likely to become a minority arch as 64-bit systems
98			become the norm. The implicit assumptions that underly the current
99			system (that most devs, users, and package maintainers use x86)
100			will become increasingly less valid.
101			* Markedly improved QA for x86. Assuming that the author's own is
102			behavior is representative, most x86 devs run ``~x86`` systems.
103			Thus, the assumption that devs are good ``x86`` testers is not really
104			valid. One obvious consequence is that packages tend to languish in
105			``~x86`` for a very long time, since x86 devs running ``~x86`` have little
106			cause to notice that a package has not been marked stable. The much larger
107			effect, though, is that it is rare for ``x86`` packages to be stabled in
108			the context of a full ``x86`` tree, so the big picture of a stable
109			system, not just a stable package, is lost. This approach of stabling
110			in the context of a full stable ``arch`` tree, it has been argued_, is
111			the fundamental reason why the non-x86 archs have notably better QA
112			than does the x86 arch.
113
114			.. _argued: http://thread.gmane.org/gmane.linux.gentoo.devel/30369
115
116			Implementation
117			==============
118
119			Creation of a robust x86 team is already underway. The more vital step
120			is the official change in policy, along with a sustained effort to get
121			existing x86 devs to go along with it.
122
123			Alternative Ideas
124			=================
125
126			Stuart_ has suggested the creation of a new arch keyword: "[-]maint", which
127			would exist in tandem with the normal arch keywords, thereby making the
128			package maintainer's intention explicit. Ciaranm has responded that by
129			definition a package in ``~arch`` is a candidate for ``arch``, so a package's
130			mere presence in the tree (without being in ``package.mask``) should indicate
131			the package maintainer's intention. There was a fair bit of discussion about
132			whether the idea should be a "maint" keyword, or named something else, or an
133			entirely different variable, etcetera, but the basic gist didn't change much.
134
135			Jstubbs notes that it could be a very good idea if all non-arch devs worked in
136			overlays, but that new portage (gensync) support would be needed to make it
137			truly viable. Stuart pointed out that php5 support was handled just that way.
138			One author's view is that this approach would make the "package in ``~arch``
139			means that it's a de-facto candidate for ``arch``" interpretation even more
140			valid.
141
142			Ciaranm and weeve have noted that it is occasionally necessary for arch teams
143			to override a package maintainer when it comes to stabling a package. Stuart
144			has asserted that in those cases the arch team should be willing to take on
145			the support burden for that package.
146
147			.. _Stuart: http://thread.gmane.org/gmane.linux.gentoo.devel/31060
148
149			Backwards Compatibility
150			=======================
151
152			Not really an issue here.
153
154
155			Copyright
156			=========
157
158			This document has been placed in the public domain.