This page documents the process used by the release engineering team to produce official FreeBSD releases. Comments, suggestions, and additional material are welcome. This is, as always, a work in progress.
New releases of FreeBSD are released from the -STABLE branch at approximately four month intervals. The FreeBSD release process begins to ramp up 45 days before the anticipated release date when the release engineer sends an email to the development mailing lists to remind developers that they only have 15 days to integrate new changes before the code freeze. During this time, many developers perform what have become known as ``MFC sweeps''. MFC stands for ``Merge From CURRENT'' and it describes the process of merging a tested change from our -CURRENT development branch to our -STABLE branch.
To service our most conservative users, individual release branches were introduced with FreeBSD 4.3. These release branches are created shortly before a final release is made, and after the release goes out only the most critical security fixes are merged onto the release branch. In addition to source updates via CVS, binary patchkits are available to keep systems on the RELENG_4_3 and RELENG_4_4 branches updated.
Thirty days before the anticipated release, the source repository enters a ``code slush''. During this time, all commits to the -STABLE branch must be approved by the release engineer (re@FreeBSD.org). The kinds of changes that are allowed during this 15 day period include :
After the first 15 days of the code slush, a release candidate is released for widespread testing and the code enters a ``code freeze'' where it becomes much harder to justify new changes to the system unless a serious bug-fix or security issue is involved. During the code freeze, at least one release candidate is released per week until the final release is ready. During the days leading up to the final release, the release engineering team is in constant communication with the security-officer team, the documentation maintainers, and the ports managers, to make sure that all of the different components required for a successful release are available.
When several release candidates have been made available for widespread testing and all major issues have been resolved, the final release ``polishing'' can begin.
As described in the introduction, the RELENG_X_Y release branch is a relatively new addition to our release engineering methodology. The first step in creating this branch is to ensure that you are working with the newest version of the RELENG_X sources that you want to branch from.
/usr/src# cvs up -rRELENG_4 -P -dThe next step is to create a branch point tag. A ``tag'' is CVS vernacular for a label that identifies the source at a specific point in time. By tagging the tree, we ensure that future release builders will always be able to use the same source we used to create the official FreeBSD Project releases. The branch point tag makes it easier to produce diffs against the start of the branch :
/usr/src# cvs rtag -rRELENG_4 RELENG_4_4_BP srcAnd then a new branch tag is created with :
/usr/src# cvs rtag -b -rRELENG_4_4_BP RELENG_4_4 srcNote: The RELENG_* tags are restricted for use by the CVS-meisters and release engineers.
Before the final release can be tagged, built, and released, the following files need to be modified to reflect the correct version of FreeBSD :
The release notes and errata files also need to be adjusted for + the new release (on the release branch) and truncated + appropriately (on the stable/current branch):
+ +When the final release is ready, the following command will create the RELENG_4_4_0_RELEASE tag.
/usr/src# cvs rtag -rRELENG_4_4 RELENG_4_4_0_RELEASE srcThe Documentation and Ports managers are responsible for tagging the respective trees with the RELEASE_4_4_0 tag.
Occasionally, a last minute fix may be required after the final tags have been created. In practice this isn't a problem, since CVS allows tags to be manipulated with cvs tag -d tagname filename. It is very important that any last minute changes be tagged appropriately as part of the release. FreeBSD releases must always be reproduceable. Local hacks in the release engineer's environment are not acceptable.
FreeBSD releases can be built by anyone with a fast machine and access to a source repository. (That should be everyone, since we offer anonymous CVS! See The Handbook for details.). The only special requirement is that the vn (On -CURRENT, this device has been replaced by the new md memory disk driver.) device must be available. If the device is not loaded into your kernel, then the kernel module should be automatically loaded when vnconfig is executed during the boot media creation phase. All of the tools necessary to build a release are available from the CVS repository in src/release. These tools aim to provide a consistent way to build FreeBSD releases. A complete release can actually be built with only a single command, including the creation of ISO images suitable for burning to CDROM, installation floppies, and an FTP install directory. This command is aptly named ``make release''.
To successfully build a release, you must first populate /usr/obj by running ``make world'' or simply ``make buildworld''. The release target requires several variables be set properly to build a release :
There are many other variables available to customize the release build. Most of these variables are documented at the top of src/release/Makefile. The exact command used to build the official FreeBSD 4.4 (x86) release was :
make release CHROOTDIR=/local3/release BUILDNAME=4.4-RELEASE CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_4_0_RELEASEThe release Makefile can be broken down into several distinct steps.
The FreeBSD Ports collection is a collection of over 6,000 third-party software packages available for FreeBSD. The ports team (portmgr@FreeBSD.org) responsible for maintaining a consistent ports tree that can be used to create the binary packages that accompany a given FreeBSD release.
In order to provide a consistent set of third-party packages for FreeBSD releases, every port is built in a separate chroot environment, starting with an empty /usr/local and /usr/X11R6. The requisite dependencies are installed as packages before the build proceeds. This enforces consistency in the package build process. By starting the package build in a pristine environment, we can assure that the package metadata (such as required dependencies) is accurate, and so we will never generate packages that might work on some systems and not on others depending on what software was previously installed.
The ``Ports Cluster'' for the x86 architecture currently consists of a master node (Dual Pentium III 733Mhz) and 8 slave nodes (Pentium III 800Mhz) to do the actual package builds. With this configuration, a complete package build takes over 24 hours. These machines are co-located with the other FreeBSD Project equipment at Yahoo's corner of Exodus in Santa Clara, CA.
The ``Ports Cluster'' for the Alpha architecture consists of 7 PWS 500A machines donated by Compaq and also co-located with Yahoo's facilities.
For FreeBSD 4.4 over 4.1 gigabytes of packages were created. This causes a problem for CDROM distributions because we would like to ship as many packages as possible without making the user insert another disc to satisfy dependencies. The solution is to create ``clusters'' of like packages with similar dependencies onto specific discs. The package split is performed by the portmgr team in coordination with the wishes of the general user community with respect to which packages get to appear on the first CD.
Starting with FreeBSD 4.4, the FreeBSD Project decided to release all four ISO images that were previously sold on the BSDi/Wind River Systems ``official'' CDROM distributions. Each of the four discs must contain a README.TXT file that explains the contents of the disc, a CDROM.INF file that provides meta-data for the disc so that sysinstall can validate and use the contents, and a filename.txt file that provides a manifest for the disc. This manifest can be created with a simple command :
/stage/cdrom# find . -type f | sed -e 's/\^.\///' | sort > filename.txtThe specific requirements of each CD is outlined below.
The first disc is almost completely created by ``make release''. The only changes that should be made to the disc1 directory are the addition of a 'tools' directory, XFree86, and as many popular third party software packages as will fit on the disc. The 'tools' directory contains software that allow users to create installation floppies from other operating systems. This disc should be made bootable so that users of modern PCs do not need to create installation floppy disks.
If an alternate version of XFree86 is to be provided, then sysinstall must be updated to reflect the new location and installation instructions. The relevant code is contained in src/release/sysinstall on -STABLE or src/usr.sbin/sysinstall on -CURRENT. Specifically, the files dist.c, menus.c, and config.c will need to be updated.
The second disc is also largely created by ``make release''. This disc contains a ``live filesystem'' that can be used from sysinstall to troubleshoot a FreeBSD installation. This disc should be bootable and should also contain a compressed copy of the CVS repository in the CVSROOT directory and commercial software demos in the commerce directory.
The remaining two discs contains additional software packages for FreeBSD. The packages should be clustered so that a package and all of its dependencies are included on the same disc.