Stable request

This article describes the procedure for moving an ebuild from testing to stable.

Responsibility
The primary purpose of the stabilisation process is to integrate a testing ebuild into the stable tree. This can involve maintaining the consistency of the dependency graph, basic compatibility checks with other packages, and smoke testing of the package itself.

Stabilisation is not intended to relieve a package maintainer of their responsibility to ship a quality package - the primary responsibility of ensuring that a package is a good stable candidate remains with the person approving the stabilisation request. The stabilisation process does not include more than basic functionality checks unless explicitly requested.

Requesting stabilisation
To request stabilisation of a package, file a new bug under the  component taking care to complete two special fields:


 * - a fully qualified atom optionally followed by a space-delimited list of architectures to target. If no architecture list is provided, all architectures in  are assumed
 * - indicates if additional runtime testing is should be performed beyond build and tests passing. If undefined the arch tester should use their best judgement

Examples:

If a large number of atoms are being stabilised at once, it might be preferred to use an attachment to list the atoms instead of the field. In that case, set the flag attachments so that  is set to. If multiple active attachments are flagged they will all be considered, so remove the flag from or mark as obsolete old attachments. If both the atoms field is completed and an attachment is flagged, only the atoms field is considered.

Periodically a bot will review stabilisation requests for completeness and complain if there are invalid or missing atoms, setting a  or   flag as appropriate. This allows arch team members to filter out requests that are not known-good if they wish. A series of architecture-specific saved searches are available for convenience.

Configuration
It is preferred that testing take place on a real system, inside a chroot, or within another type of non-virtualised container. Virtualisation may be acceptable in situations where it is not possible or practical to test on real hardware.

The testing system must only have stable packages installed, with no testing packages keyworded or unmasked. It should be up-to-date, and it is recommended to have as few packages installed as possible.

should have settings similar to the following:

Testing
Each package in Gentoo is different and therefore requires a slightly different approach to stabilisation. Consider the following guidelines for each class of package, and use common sense when in doubt.

USE flags
While it is preferable to test every USE flag combination, this is not always possible or appropriate. The package may have a large number of USE flags, a long compile time, or the stabilisation in question may just not call for it.

In cases where all USE flags combinations are not being tested, it is still recommended to test:
 * with all USE flags enabled
 * with all USE flags disabled
 * the default USE flag settings

Runtime testing
Consider the level of runtime testing that is required for the target package. Remember, the focus of stabilisation is to integrate a testing ebuild into the stable tree and not to identify routine bugs or regressions - that is the purpose of the package's waiting time in ~arch.

The level of runtime testing required will vary wildly based on a variety of factors. Consider the following examples:


 * Multiple days of "normal use" testing may be appropriate for a new version of
 * Basic functionality testing, such as browsing some web pages, may make sense for a new version of
 * Passing tests might be enough for
 * A leaf package such as may not require any runtime testing at all

Libraries
A new library version may introduce incompatibles with reverse dependencies. Where there's a risk of such breakage, each stable reverse dependency must be rebuilt. Beware of reverse dependencies that only use the library conditionally (eg. ).

Kernel
Kernel packages referenced in the handbook have certain exemptions from the usual stabilisation policy, so stabilisation requests are normally only filed for the first version in a long term stable branch (subsequent versions can be stabilised at the discretion of the maintainer).

First, test all available kernel options:

If that succeeds, build with your normal configuration:

After reboot, check  for anything strange and use the system as normal, trying to get a bit of uptime.

If stabilising a special feature variant such as, try to test those features.

Toolchain
New versions of toolchain packages can often introduce major changes and widespread breakage into the tree. The purpose of a stabilisation request for a toolchain package is to test the package itself on each architecture - not to detect build failures in miscellaneous packages. It is expected that such failures are managed and resolved by the maintainer (normally through tracker bugs and tinderboxing) prior to filing a stabilisation request.

Once the normal testing is successful, rebuild  (or   if the hardware permits) and once successful, observe the system in normal operation for abnormalities.

getatoms
getatoms is a simple script to get a list of atoms from a stabilisation bug. It's designed to feed atoms into another tool for processing, such as batch_stabilise.

tatt
is a tool designed to automate some of the repetitive tasks involved in arch testing. Currently only version 9999 supports working with a git ebuild repository and the bugzilla atom field.

For each job, tatt produces a series of scripts allowing the user to control exactly what is performed:

Configuration
tatt has a variety of configuration options (see ), but there is a few that must be set to ensure useful operation of all functions.

Sample workflow
First, start a new job:

Now the various scripts are available for use:

Next, build the package and perform whatever testing is necessary:

A report is also produced summarising the build status of each USE flag combination:

Once everything looks good, commit the keyword change:

Finally, update the bug and cleanup the job:

QA violations
Most of these violations will be detected automatically using the testing tool, but are also described here for completeness.


 * Does not respect CC
 * Does not respect CFLAGS
 * Does not respect LDFLAGS
 * Bundled symbols
 * Insecure symbols
 * Installs documentation outside of /usr/share/doc/${PF}
 * ELF files found in /usr/share

Architecture-specific notes
A number of items described in earlier sections, such as checking of reverse dependencies and miscellaneous QA checks, are architecture-neutral. At a stabilisation level, the primary responsibility for carrying out these checks rests on the first architecture to stabilise an ebuild. Subsequent architectures may assume that these checks have been completed and skip them if they wish.

amd64

 * Any developer may perform stabilisations - it is not necessary to be on the arch team
 * must be added to

arm
The ARM project supports four variants - armv4, armv5, armv6, and armv7. In addition to regular testing, the package must be build tested on each variant. If access to each physical variant is not possible,  is acceptable.

x86

 * Any developer may perform stabilisations - it is not necessary to be on the arch team
 * It is acceptable to stabilise in an chroot on
 * It is generally acceptable to stabilise a package with only a build test on if it is already stable on

Acknowledgements
Most of this guide was shameless stolen from many sources, including but not limited to:
 * Agostino Sarubbo
 * Various arch teams