User:Dilfridge/GLEP:72

Abstract
This GLEP provides specifications for a new file in the profiles base direcrtory, "arches.desc". Its intent is to allow more fine-grained repoman check control, and in particular to help moving architectures from stable to unstable while keeping the unstable dependency tree consistent, or moving architectures from unstable to stable while easily preparing a consistent stable dependency tree.

"arches.desc" specifies whether an architecture, as opposed to a profile, is to be considered stable. It does not replace profiles.desc, but supplements it; profiles.desc still describes the profiles of each architecture.

We use the term architecture here in the colloquial sense, as also used by the Package Manager Specification in section 4.4.1 (describing profiles.desc), and corresponding in the terminology of GLEP 53 to a "keyword" (which, however, even if more precise is not consistently used in practice).

Motivation
At the moment we have several cases where repoman finds its limits:

a) An architecture loses its stable status (imagine c128), but the architecture team doesn't want to drop all the stable keywords since they are useful for stage building. Since the stable keywords on c128 are then only an arch-team-internal thing, everyone is allowed to drop the latest stable version of a package, and it's the arch team's responsibility to keep their "unofficial stable tree" straight. This is how at the time of the writing of this GLEP s390, sh, and m68k are handled. Right now this means that we have to set all *profiles* of this arch to profile status "exp" in profiles.desc, otherwise repoman throws errors about a broken stable dependency tree. If we do that, repoman does however also not check ~c128 consistency, meaning that the ~c128 dependency tree will soon be broken as well due to negligence. Given arches.conf as described below, one could set the architecture c128 to "mixed" status and keep stable profiles. This results in stable keywords being ignored, but consistency of the ~c128 dependency tree is still enforced.

b) An architecture prepares for becoming a stable architecture (think arm64). So, first the ~arm64 dependency tree should be fine, and then stable keywords can be added. However, to avoid repoman errors as long as the stable dependency tree is not complete yet, the profiles need to be set to dev/exp, and again this brings the danger of the ~arm64 dependency tree getting inadvertently broken. Again the combination of setting the architecture to "mixed" in arches.desc and profiles to stable helps.

Finally, at the moment the "semi-official" algorithm to figure out if an architecture is stable in the colloquial sense (e.g., requires stabilization requests) is to check if the architecture has any stable profile. This makes non-stable arches which want to keep a consistent dependency tree (think mips) impossible. Reading the architecture status from arches.desc instead solves this problem.

File and format
In the main profiles directory, a file "arches.desc" is added. Name and location are chosen in analogy to the existing "profiles.desc" file. The format of "arches.desc" is as follows:

Every # starts a comment; the character and the rest of the line are ignored. Every blank line is ignored. Otherwise the file consists of two whitespace-separated columns: Additional columns are ignored to allow for future revisions of this document.
 * first column: architecture name (keyword)
 * second column: one of the three values "stable", "mixed", "unstable"

An example arches.desc file might look as follows: amd64  stable x86    stable     # not for long
 * 1) Example arches.desc file

m68k   mixed      outdated mips   unstable

Initial value in the gentoo repository
On introduction, the setting will be "stable" for all stable architectures, "mixed" for all architectures where "inofficial" stable keywords are maintained and are present in the repository by the arch teams (m68k, sh, s390), and "unstable" everywhere else.

Meaning of the values for repoman
Which profiles of any architecture are tested is still controlled by profiles.desc (and -d / -e switches). How these tests are precisely performed is specified as follows:

stable
When a profile of an architecture arch is tested, then repoman checks consistency of the dependency tree for "arch" and for "~arch" separately.

This is the current behaviour and shall be the default if nothing is specified for an architecture.

mixed
When a profile of an architecture is tested, then repoman treats "arch" in ebuilds as "~arch", and tests consistency only for "~arch".

A new switch for repoman may be provided to temporarily upgrade an architecture from "testing" to "stable" status (for architecture team work).

unstable
When a profile of an architecture is tested, then repoman treats "arch" as an error and aborts. Consistency is only tested for "~arch".

Meaning of the values for other tools
All architectures with the value "stable" are considered as stable architectures, in the sense that
 * they require stabilization requests on bugzilla, which are handled by an arch team
 * they may, e.g., be listed first by tools such as eshowkw
 * and similar, to the discretion of tool authors

Choice of file format, name, and location
The function of this file is very closely related to the existing profiles.desc. With this in mind, the same location, the same style of file name, and essentially the same file format (space-separated columns) is chosen.

Choice of value names
The name "stable" signifying a fully stable architecture is an obvious choice. "unstable" for an architecture that does not carry any stable keywords at all is equally obvious. Describing the intermediate state is a more complex matter; "mixed" is a compromise.

Backwards Compatibility
Essentially two cases need to be discussed. Here "old system" designates a Gentoo installation where package manager and/or utilities do not provide arches.desc support yet, "new system" an installation where they do.

arches.desc present and old system
Utilities ignore the unknown file.

Repoman and other tools may emit surplus dependency errors when profiles are checked on arches that are "mixed" (they check the consistency of the stable tree alone, which may fail, since "arch" is supposed to be treated like "~arch"). This affects only development work and can be fixed by updating repoman.

No arches.desc present and new system, or arch not listed in arches.desc
Arches are treated as "stable" by repoman (the current behaviour), with profile status according to profiles.desc. Gentoolkit and other tools trying to determine a list of stable arches shall fall back to the current method of determining stable arches by scanning profiles.desc for stable profiles.

arches.desc in overlays
If arches.desc is present in several repositories, then the strictest setting for an architecture wins. Using arches.desc outside the gentoo (or alternative) master repository however is discouraged.

Copyright
This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/.