25.5 Tracking a Development Branch

There are two development branches to FreeBSD: FreeBSD-CURRENT and FreeBSD-STABLE. This section provides an explanation of each and describes how to keep a system up-to-date with each respective tree. FreeBSD-CURRENT will be discussed first, then FreeBSD-STABLE.

25.5.1 Staying Current with FreeBSD

FreeBSD-CURRENT is the “bleeding edge” of FreeBSD development. FreeBSD-CURRENT users are expected to have a high degree of technical skill and should be capable of solving difficult system problems on their own. If you are new to FreeBSD, track FreeBSD-STABLE instead.

25.5.1.1 What Is FreeBSD-CURRENT?

FreeBSD-CURRENT is the latest working sources for FreeBSD. This includes work in progress, experimental changes, and transitional mechanisms that might or might not be present in the next official release of the software. While many FreeBSD developers compile the FreeBSD-CURRENT source code daily, there are periods of time when the sources are not buildable. These problems are resolved as quickly as possible, but whether or not FreeBSD-CURRENT brings disaster or greatly desired functionality can be a matter of when the source code was synced

25.5.1.2 Who Needs FreeBSD-CURRENT?

FreeBSD-CURRENT is made available for three primary interest groups:

  1. Members of the FreeBSD community who are actively working on some part of the source tree and for whom keeping “current” is an absolute requirement.

  2. Members of the FreeBSD community who are active testers, willing to spend time solving problems in order to ensure that FreeBSD-CURRENT remains as sane as possible. These testers wish to make topical suggestions on changes and the general direction of FreeBSD, and submit patches to implement them.

  3. Those who merely wish to keep an eye on things, or to use the current sources for reference purposes. These people also make the occasional comment or contribute code.

25.5.1.3 What Is FreeBSD-CURRENT Not?

  1. A fast-track to getting new features before the next release. Pre-release features are not yet fully tested and most likely contain bugs.

  2. A quick way of getting bug fixes, though the fix is just as likely to introduce new bugs as to fix existing ones.

  3. In no way “officially supported”.

25.5.1.4 Using FreeBSD-CURRENT

  1. Join the freebsd-current and the svn-src-head lists. This is essential in order to see the comments that people are making about the current state of the system and to receive important bulletins which may be critical to the system's continued health.

    The svn-src-head list records the commit log entry for each change as it is made, along with any pertinent information on possible side-effects.

    To join these lists, go to http://lists.FreeBSD.org/mailman/listinfo, click on the list to subscribe to, and follow the instructions. In order to track changes to the whole source tree, subscribe to the svn-src-all list.

  2. Grab the sources from a FreeBSD mirror site using one of the following methods:

    1. Use svn to check out the desired development or release branch. This is the recommended method, providing access to FreeBSD development as it occurs. Checkout the -CURRENT code from the head branch of one of the Subversion mirror sites. Due to the size of the repository, it is recommended that only desired subtrees be checked out.

    2. Use the CTM facility. If you have bad connectivity such as high price connections or only email access, CTM is an option, but it is not as reliable as Subversion. For this reason, Subversion is the recommended method for any system with Internet connectivity.

  3. If you plan to run, and not just look at the sources, download all of FreeBSD-CURRENT, not just selected portions. Various parts of the source depend on updates elsewhere, and trying to compile just a subset is almost guaranteed to cause problems.

    Before compiling FreeBSD-CURRENT, read /usr/src/Makefile very carefully. Install a new kernel and rebuild the world the first time through as part of the upgrading process. Read the FreeBSD-CURRENT mailing list and /usr/src/UPDATING to stay up-to-date on other bootstrapping procedures that sometimes become necessary on the road to the next release.

  4. Be active! FreeBSD-CURRENT users are encouraged to submit their suggestions for enhancements or bug fixes. Suggestions with accompanying code are received most enthusiastically!

25.5.2 Staying Stable with FreeBSD

25.5.2.1 What Is FreeBSD-STABLE?

FreeBSD-STABLE is the development branch from which major releases are made. Changes go into this branch at a different pace, and with the general assumption that they have first gone into FreeBSD-CURRENT for testing. This is still a development branch, however, and this means that at any given time, the sources for FreeBSD-STABLE may or may not be suitable for any particular purpose. It is simply another engineering development track, not a resource for end-users.

25.5.2.2 Who Needs FreeBSD-STABLE?

Those interested in tracking or contributing to the FreeBSD development process, especially as it relates to the next “point” release of FreeBSD, should consider following FreeBSD-STABLE.

While security fixes go into the FreeBSD-STABLE branch, one does not need to track FreeBSD-STABLE to receive security fixes. Every security advisory for FreeBSD explains how to fix the problem for the releases it affects which are not yet EOL. [1].

While the FreeBSD-STABLE branch should compile and run at all times, this cannot be guaranteed. While code is developed in FreeBSD-CURRENT before including it in FreeBSD-STABLE, more people run FreeBSD-STABLE than FreeBSD-CURRENT, so it is inevitable that bugs and corner cases will sometimes be found in FreeBSD-STABLE that were not apparent in FreeBSD-CURRENT.

For these reasons, one should not blindly track FreeBSD-STABLE. It is particularly important not to update any production servers to FreeBSD-STABLE without first thoroughly testing the code in that development environment.

Except for those users who have the resources to perform testing, it is recommended that users instead run the most recent release of FreeBSD, and use the binary update mechanism to move from release to release.

25.5.2.3 Using FreeBSD-STABLE

  1. Join the freebsd-stable list in order to stay informed of build-dependencies that may appear in FreeBSD-STABLE or any other issues requiring special attention. Developers will also make announcements in this mailing list when they are contemplating some controversial fix or update, giving the users a chance to respond if they have any issues to raise concerning the proposed change.

    Join the relevant SVN list for the branch being tracked. For example, users tracking the 9-STABLE branch should join the svn-src-stable-9 list. This list records the commit log entry for each change as it is made, along with any pertinent information on possible side-effects.

    To join these lists, go to http://lists.FreeBSD.org/mailman/listinfo, click on the list to subscribe to, and follow the instructions. In order to track changes for the whole source tree, subscribe to svn-src-all.

  2. To install a new system in order to run monthly snapshots built from FreeBSD-STABLE, refer to Snapshotsfor more information. Alternatively, it is possible to install the most recent FreeBSD-STABLE release from the mirror sites and follow the instructions below to upgrade the system to the most up-to-date FreeBSD-STABLE source code.

    Several methods are available to upgrade from a FreeBSD mirror site on a system already running a previous release of FreeBSD:

    1. Use svn to check out the desired development or release branch. This is the recommended method, providing access to FreeBSD development as it occurs. Branch names include head for the current development head, and branches identified in the release engineering page, such as stable/9 or releng/9.0. URL prefixes for Subversion checkout of the base system are shown in Subversion mirror sites. Because of the size of the repository, it is recommended that only desired subtrees be checked out.

    2. Consider using CTM if you do not have a fast connection to the Internet.

  3. If you need rapid on-demand access to the source and communications bandwidth is not a consideration, use Subversion. Otherwise, use CTM.

  4. Before compiling FreeBSD-STABLE, read /usr/src/Makefile carefully. Install a new kernel and rebuild the world the first time through as part of the upgrading process. Read FreeBSD-STABLE mailing list and /usr/src/UPDATING to keep up-to-date on other bootstrapping procedures that sometimes become necessary on the road to the next release.

Notes

[1]

For a complete description of the current security policy for old releases of FreeBSD, refer to http://www.FreeBSD.org/security/.