User:Dilfridge/GLEP:72

GLEP 72: Architecture stability status file
Type	Standards Track
Status	Draft
Author	Andreas K. Hüttel <dilfridge@gentoo.org>
Editor
Replaces
Replaced by	(none)
Requires
Post History

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.

Specifications for profiles/arches.desc

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 three whitespace-separated columns:

first column: architecture name (keyword)
second column: one of the three values "stable", "mixed", "unstable"
third column: does this arch require stabilization requests on bugzilla, "yes" or "no"

Additional columns are ignored to allow for future revisions of this document.

For second column value "stable", the only valid value for the third column (and the default if not given) is "yes".
For second column value "mixed", the default value for the third column is "no".
For second column value "unstable", the only valid value for the third column (and the default if not given) is "no".

An example arches.desc file might look as follows:

# Example arches.desc file
amd64   stable     yes
x86     stable

m68k    mixed      no
mips    unstable

Initial value in the gentoo repository

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

Meaning of the second column values for repoman, pkgcore or similar QA tools

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 is tested, then the consistency of the dependency tree for "arch" and for "~arch" is tested separately.

This is the current behaviour and shall be the default if nothing is specified for an architecture in arches.desc, or if the file is missing entirely.

mixed

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

A new command line switch for repoman or other tools may be provided to temporarily upgrade an architecture from "mixed" to "stable" status (for architecture team work).

unstable

When a profile of an architecture is tested, then "arch" is treated as a fatal error. Consistency of the dependency tree is only tested for "~arch".

Meaning of the second column values for other tools

All architectures with the value "stable" are considered as stable architectures, in the sense that they may, e.g., be listed first by tools such as eshowkw.

The canonical way for a tool to find the list of "stable architectures" shall be to find the architectures with value "stable" in the second column.

Rationale

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. A repoman-specific location or format does not make sense since the file explicitly also addresses other tools such as, e.g., gentoolkit.

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/.