Project:RelEng/Release Guidelines
Gentoo nowadays is a rolling release distro and the contents of this page no longer apply.
This guide covers both the QA and release guidelines for the Gentoo Linux biannual release system.
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).
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.
| Guideline | Description |
|---|---|
| Is the architecture on the release list? | Contact the Release Operations Manager if it is not. The release list will be posted by the Operations Manager at the beginning of the release process. It is also available on the release information page for the specified release. |
| Have the features designated in the release Feature Roadmap applicable to the architecture been completed? | All features that are relevant to the architecture must be completed for the release. Contact the Operations Manager if there are extenuating circumstances which will prevent these features from being completed. |
| Are the applicable core packages listed on the release information page being used? | If applicable to the arch, certain core packages are to be utilized to maintain consistency. |
| Is the installation documentation up-to-date? | The Architecture Release Coordinator should be in contact with the Release Engineering Documentation Liaison at all times to ensure that the documentation released is in sync with the release itself. |
| Are all critical bugs from the last release fixed for the coming release? | Scour Bugzilla for bugs from the last release. Fix as many as possible. The goal is perfection. Bugs will be assigned to the release@gentoo.org alias. Bugs for a release should not be changed into a RESOLVED state until a release has been made available with the bug fix. |
| Regression Testing | Do the CD images and stages compile and run as expected on each of your supported subarchitectures? Refer to the regression testing guide section for instructions on how to properly run a Gentoo regression test. |
| Does the Gentoo Documentation Project (GDP) have all of the necessary information required for the release documentation? | The GDP requires a listing of all bootable kernels on each bootable CD, a listing of all supported boot options on each bootable CD, the output of find on a mounted CD from each category (both bootable CDs and Packages CDs), and the output of find on a booted Universal/Minimal InstallCD. The information can be sent to the Release Engineering GDP Liaison, who is listed on the Release Engineering Project Page, or to the Release Operations Manager. |
| Are the InstallCD and PackageCD specfile templates followed? | The templates for the bootable InstallCDs and non-bootable PackageCDs specify an essential core group of packages that maintain compatibility and consistency across all architectures. It is essential that the core group of packages specified is used. |
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.
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:
| Guideline | Description |
|---|---|
| Are the requirements of the development/QA phase QA checklist completed? | Are all of the requirements specified in the development/QA Phase QA Checklist completed, as specified, and in form? |
| Are all of the components necessary for a release present? | Please refer to the list of components necessary for a release. |
| Layout | Do the InstallCD, Package CD, and stages all conform to the naming and layout conventions set forth by Release Engineering? |
| Are the release notes in forms available both online and on the InstallCD? | Make sure that the release notes are present in the locations specified by the layout convention. |
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 propagation 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.
Resources
Necessary components for a release
The following components are necessary for an official release:
| Component | Description |
|---|---|
| Bootable InstallCDs | This includes both the Universal and Minimal InstallCD images that users can use to boot a wide variety of hardware for the end goal of installing Gentoo Linux. There are two flavors of the bootable InstallCD, the Universal and the Minimal. A Universal InstallCD contains a set of stage3s for all supported subarches as well as the distfiles required to install from a stage3 without a network connection. A Minimal InstallCD only contains the necessary items needed to boot a system. Please refer to the layout specifications and the Catalyst specfile template for the required layout and core packages of both CDs. Both images are required for an official release. |
| Packages CD | A non-bootable CD that contains a Gentoo Reference Platform (GRP) set used for off-network installation. A user should not need an Internet connection to install when using this disc. Please refer to the layout specifications for PackageCD layout, and the Catalyst specfile template for a list of required packages. |
| Bootable LiveCD | A bootable LiveCD image with the Gentoo Linux Installer may be substituted for the requirement for a Universal InstallCD and a PackageCD. This is the only case in which a Universal InstallCD and PackageCD may be missing from a given architectures release and it to still be considered complete and official. |
| Installation stages | Stage 1, 2, and 3 tarballs that can be used to install Gentoo Linux. |
| Release Notes | Notes that follow the template specified by Release Engineering that detail important aspects about the release. |
| DIGESTS and CONTENTS | Both MD5 and SHA1 hashes are required to be generated for all release media. These hashes are automatically created by catalyst, and should be included with the media. A CONTENTS file should be generated for the following media: Minimal InstallCD (booted), Universal InstallCD (both booted and non-booted), PackageCD, and LiveCD. |
Regression testing guide
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 CD layout
Install/Live/Package CDs 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.
| Component Name | Naming convention | Example |
|---|---|---|
| Universal Bootable InstallCD | install-${arch}-universal-${relver}.iso | install-x86-universal-2005.1.iso |
| Minimal Bootable InstallCD | install-${arch}-minimal-${relver}.iso | install-alpha-minimal-2005.1.iso |
| Bootable LiveCD | livecd-${arch}-${relver}.iso | livecd-x86-2005.1.iso |
| Packages CD | packages-${subarch}-${relver}.iso | packages-pentium4-2005.1.iso |
| Installation Stages | stage{1,2,3}-${subarch}-${relver}.tar.bz2 | stage3-ppc-2005.1.tar.bz2 |
| Installation Stages that are a different release type, such as hardened stages or selinux stages | stage{1,2,3}-${subarch}-${reltype}-${relver}.tar.bz2 | stage2-athlon-xp-selinux-2004.0.tar.bz2 |
| Release Notes | ${arch}-release-notes.xml | sparc-release-notes.xml, placed in CVS at gentoo/xml/htdocs/proj/en/releng/release/${relver}/${arch} The current template and autogeneration tool can be found in CVS at gentoo/src/relnotes |
Universal install CDs
The universal bootable install CD is to adhere to the following layout standard:
| Directory | Description |
|---|---|
| /distfiles | Directory where all of the necessary distfiles are stored to install from a stage3 tarball with no network connection. |
| /docs | Directory where the release notes and the Handbook reside. The Handbook has its own directory structure, /docs/handbook/{html,pdf,txt}, with each subdirectory being for a respective format of the Handbook. The final versions of both the release notes and the Handbook will be linked off of the release information page. |
| /boot (/isolinux on x86/amd64) | Autogenerated directory for the bootloader. |
| /snapshots | Directory containing the snapshot used to build the release components. |
| /stages | Directory containing the stage3 tarballs for each supported subarch. |
| /zisofs (optional) | Autogenerated directory for the zisofs runtime. Only applicable to architectures that use the zisofs compression scheme. Using zisofs should only be considered if squashfs is unavailable for the architecture due to technical problems, such as kernel panics. |
Minimal install CDs
The minimal bootable install CD is to adhere to the following layout standard:
| Directory | Description |
|---|---|
| /boot (/isolinux on x86/amd64) | Autogenerated directory for the bootloader. |
| /zisofs (optional) | Autogenerated directory for the zisofs runtime. Only applicable to architectures that use the zisofs compression scheme. Using zisofs should only be considered if squashfs is unavailable for the architecture due to technical problems, such as kernel panics. |
Both InstallCDs may use a wide variety of kernels to ensure user compatibility. 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.
Package install CDs
The package CD is to adhere to the following layout standard:
| Directory | Description |
|---|---|
| /${app-category}/${package} | The PackageCD will be laid out in the same fashion as /usr/portage/packages. |
The command for creating the PackageCD ISO file is:
root #cd grp-${subarch}-${relver}/cd2
root #mkisofs -R -J -l -V "${subarch} Packages" -o ../packages-${subarch}-${relver}.iso .
Live and Package CD template Catalyst spec files
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.
This page is based on a document formerly found on our main website gentoo.org.