Gentoo Linux Release Guidelines

1.  Introduction

Main Goals

A Gentoo Linux release should strive to be two things -- high quality and low-stress. The guidelines set forth in this document are an attempt to promote both while keeping within a deadline.

Release Overview

For the Architecture Release Coordinators, the release process is binary; there is the off-time which is spent in development and QA, and there is the final release process which is spent doing final release QA. During the entire process, Release Engineering and the Architecture Release Coordinators will work closely together on every aspect of the release. A critical aspect of the release process is communication. If there are questions or comments regarding any part of the release process, the Architecture Release Coordinators should contact the Release Operations Manager, whose current e-mail is always found on the Release Engineering project page. Specific information on the release can always be found on the release information page, which is at http://www.gentoo.org/proj/en/releng/release/${relver}/releng/${relver}.xml, where ${relver} is the release version (e.g. 2005.1).

2.  Development/QA Phase

Development/QA Phase Process

Architecture Release Coordinators will spend most of their time in this phase since the final release phase takes up only a small percentage of the time spent on a release. The time difference is not an indication that the final release process is less important than the development/QA phase, but rather an understanding that most of the QA for the release will have been done in the development/QA phase. The final release phase has its own QA requirements that will be covered later in this guide.

The entire development/QA phase should be spent fixing and closing bugs, tackling the Feature Request List for the upcoming release, and constantly ensuring that the release conforms to the QA guidelines set forth by Release Engineering. It is strongly recommended that the Architecture Release Coordinator set a scheduled build cycle so that bugs and QA can be timely addressed throughout the entire process. For example, weekly or bi-weekly builds give the Architecture Release Coordinator a "heads up" on what is going on with their release.

During this phase, Release Engineering is available at all times for any and everything. If there are questions or concerns, hardware or resource requests, or anything else, please contact the Release Operations Manager.

Development/QA Phase QA Guidelines

The following QA guidelines should be worked towards constantly during this phase of the release. Doing so will ensure that the architecture to be released will in fact be released on-time and complete. Release Engineering reserves the right to block the release of any architecture that does not conform to these QA guidelines. This ensures a consistent face for the distribution to our user base.

3.  The Transition from Development/QA to Final Release

The Transition Process

The transition from the development/QA phase to the final release phase is not one that can be wholly defined by a date. The transition takes place when the QA guidelines for the development/QA phase have been met in full. At that time, the architecture to be released is ready to move into the final release phase.

4.  The Final Release Phase

Final Release Process

The final release phase of the release process is the polish on everything that has been done up to this point. The ultimate goal of this phase is to have high-quality release components on the master mirror at least five days before the release date so that the release components have adequate time to be staged, or propagated, onto the other mirrors.

The final QA checklist consists of the following:

When the Architecture Release Coordinator feels that their release components meet or exceed all of the QA guidelines, they will then upload them to the Release Engineering staging machine and inform Release Engineering so that the final approval process can begin. The final approval from Release Engineering will consist of a rundown of the final QA checklist and a check of each release component's digests. Assuming the release components pass the final approval from Release Engineering, they will be signed by Release Engineering's GPG key, and placed into the proper staging are on the Release Engineering staging machine for turnover to the Release Infrastructure Liason for propgation to the master mirror.

Only when the release components meet both the QA of the development/QA phase and the final QA will they be uploaded to the mirrors to be released. If any of the components are out of order, Release Engineering will work with the Arch Release Coordinator to fix the offending component. To have an on-time release, it is imperative that the Architecture Release Coordinator ensures that all QA is met before Release Engineering approval. Release Engineering approval should be the last check that the release components receive, not the first.

5.  Resources

Necessary Components for a Release

The following components are necessary for an official release:

Regression Testing HOWTO

Regression testing is a key aspect of QA. The regression testing process is done by running a comprehensive set of tests that emulate real-world scenarios. Regression testing is not necessarily hard, but it is time consuming. A good portion of the release process should be spent regression testing as it is the most beneficial way to identify bugs and errata.

The regression testing procedure is quite straight forward. For each InstallCD/LiveCD, follow the installation instructions verbatim. Once that is complete, try a complete GRP installation using the Installation Handbook. Once that is complete, restart the process using a different subarchitecture or GRP set. The goal is to run through the Installation Handbook as many different times as possible. The more randomness that is introduced to packages, methods, and subarches, the more chances that bugs will be identified before the final release.

Naming Conventions and InstallCD/LiveCD/PackageCDs Layout

InstallCD/LiveCDs/PackageCDs and stages are to adhere to the following naming conventions, where ${arch} is the main architecture, ${subarch} is the subarchitecture, ${reltype} is a special type identifier, and ${relver} is the release version number.

The Universal bootable InstallCD is to adhere to the following layout standard:

The Minimal bootable InstallCD is to adhere to the following layout standard:

Both InstallCDs may use a wide variety of kernels to ensure user compabibility. The kernels will be named gentoo-${kver}-${special_opt}, where ${kver} is the main version of the kernel, such as 2.6, and ${special_opt} is an optional special identifier, such as nofb. An example of a kernel name with a special identifier would be gentoo-2.6-nofb.

Both of the bootable InstallCDs will contain a standard motd in the booted FS on the CD. The motd will be the first thing that a user sees after they get a prompt their CD environment, and it will contain important information. This file is generated by catalyst.

The PackageCD is to adhere to the following layout standard:

The command for creating the PackageCD ISO file is:

# cd grp-${subarch}-${relver}/cd2
# mkisofs -R -J -l -V "${subarch} Packages" -o ../packages-${subarch}-${relver}.iso .
			

LiveCD and PackageCD template Catalyst Specfiles

Catalyst livecd-stage1 specfile template for both the Universal and Minimal bootable InstallCDs.

Catalyst livecd-stage2 specfile template for both the Universal and Minimal bootable InstallCDs.

Catalyst specfile template for the PackageCD.

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.