path: root/glep-0072.rst

---
GLEP: 72
Title: Architecture stability status file
Author: Andreas K. Hüttel <dilfridge@gentoo.org>
Type: Standards Track
Status: Deferred
Version: 1
Created: 2017-05-06
Last-Modified: 2019-06-10
Post-History: 2017-05-06
Content-Type: text/x-rst
---

Status
======

Marked as deferred by GLEP editor Ulrich Müller on 2019-06-10, due to
inactivity.


Abstract
========

This GLEP provides specifications for a new file in the profiles base
directory, ``arches.desc``. Its intent is to allow more fine-grained repoman
check control, and in particular to help moving architectures from stable to
testing while keeping the testing dependency tree consistent, or moving
architectures from testing 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
   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 "testing" 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 "testing" 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 two
whitespace-separated columns:

- first column: architecture name (keyword)
- second column: one of the four values ``stable``, ``testing``, ``unstable``,
  ``broken``

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

An example arches.desc file might look as follows::

    # Example arches.desc file
    amd64   stable
    x86     stable     # not for long

    mips    testing
    m68k    unstable   outdated

Initial value in the gentoo repository
--------------------------------------

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

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

Which profiles of the architecture are tested is still controlled
by profiles.desc (and ``-d`` / ``-e`` switches).

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

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

Which profiles of the arch are tested is still controlled by profiles.desc
(and ``-d`` / ``-e`` switches).

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

Which profiles of the arch are tested is still controlled by profiles.desc
(and ``-d`` / ``-e`` switches).

broken
~~~~~~
Repoman is not testing any profiles of this architecture, irrespective
of the settings in profiles.desc.

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


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 ``testing`` (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
https://creativecommons.org/licenses/by-sa/3.0/.