Sat, 20 Jun 2009

What is really meant by "STABLE" branches in FreeBSD.

A question I am routinely asked by people is what is the latest stable FreeBSD release. People are often tripped up by the fact that there are usually two releases listed on the front page of FreeBSD.org. The best way to answer that question is to explain how branches are done in FreeBSD. The question almost always comes from people who don't understand the details so I'll do my best to explain them here.

Perhaps it's best explained in picture form (somewhat simplified for explanation purposes): 

---V-------------------------------V----------------------> CURRENT
    \-V------V----V-----------------\---> RELENG_6
       \------\----\--> RELENG_6_0   \
               \----\--> RELENG_6_1   \
                     \----> RELENG_6_2 \---V---V-------> RELENG_7
                                            \---\---> RELENG_7_0
                                                 \------> RELENG_7_1

Tag:       | Meaning:
.          | CURRENT
RELENG_6   | 6-STABLE (at the time of fetching)
RELENG_6_0 | 6.0-RELEASE-WITH-PATCHES-FOR-SECURITY-AND-MAJOR-ERRATA
RELENG_6_1 | 6.1-RELEASE-WITH-PATCHES-FOR-SECURITY-AND-MAJOR-ERRATA
RELENG_6_2 | 6.2-RELEASE-WITH-PATCHES-FOR-SECURITY-AND-MAJOR-ERRATA
RELENG_7   | 7-STABLE (at the time of fetching)
RELENG_7_0 | 7.0-RELEASE-WITH-PATCHES-FOR-SECURITY-AND-MAJOR-ERRATA
RELENG_7_1 | 7.1-RELEASE-WITH-PATCHES-FOR-SECURITY-AND-MAJOR-ERRATA

There is a lot going on here so we'll start with the terminology. In FreeBSD, "CURRENT" is the very tip of the tree, "STABLE" is a branch off of that tree, and "RELEASE" are branches off of the STABLE line. In FreeBSD there are multiple STABLE branches and each one has multiple RELEASE branches off of it. With that picture and terminology in mind it's best to next explain what gets committed into each branch.

All new commits go into head (CURRENT) first - there are very few exceptions to this. Simply leaving things in head would make for a pretty hectic process for consumers of the FreeBSD source code as people/companies often use FreeBSD as a base for a product. Only having CURRENT to develop a product with is never a good idea. After some settling time in head a commit can possibly be merged to a STABLE branch.

STABLE branches provide a point in the tree where the team has decided that data structures look good and are not going to change. I'll provide more details on what this means later. The most important factor in determining what can be merged from CURRENT (MFC, sometimes called merge from head (MFH)) to a STABLE branch is something called ABI stability. I'll explain what this means later but for now the commit is generally not allowed if it breaks the ABI. It's important to note that not all commits in head get merged to a STABLE branch. It really depends upon what it is and if it is deemed important enough to make it into the next release off that particular STABLE branch. Something that often trips up users of FreeBSD is that a STABLE branch is still a development branch. Due to the way commits are done in CURRENT first and merged into a STABLE branch later it's usually the case that a STABLE branch is more stable (in the "least likely to crash" sense) but it's important to note that it is still an active development effort.

RELEASE branches are branched off of a STABLE line and are the most tightly controlled of them all. These only get security and major errata updates. In the "least likely to crash" sense, a RELEASE branch is the right choice.

If all that makes sense then it's time to explain what ABI stability is and why it is so important to the FreeBSD development model. Imagine a situation where a company is building a something with FreeBSD. If they were using CURRENT they would be subject to any of the data structure changes going on. If any of these changes were to affect their code they would have to adjust their code. By picking STABLE branch they are not subject to any data structure changes (which is probably the biggest worry as other parts of the ABI are so rarely changed), nor any of the other things which could possibly break ABI. Beyond providing a slightly more tested area for users and consumers a STABLE branch allows for code to be built on FreeBSD that is guaranteed to work across the lifetime of the STABLE branch. This allows for resources to be better utilized. Compare that to other development efforts where not only is the ABI constantly broken but entire subsystems are ripped out and replaced between releases. Imagine having to keep track of what changed and what that means to your product. By picking a STABLE branch that worry is lessened (you should still pay attention to the commits to see if they provide new features or bug fixes that interest you) because you know the underlying binary interface you are using will not change.

So what does this mean to you? If you're an average user who just wants things to work I would recommend a RELEASE branch and upgrading between them when a new one is made. If you're a company building something using FreeBSD I would recommend following a STABLE branch. If you have the resources and are looking to the future I would also recommend that as a new STABLE branch nears you focus on moving your code to CURRENT for testing. This gives you the ability to maintain releases based upon code in a STABLE branch while making sure that you have an upgrade path to the next STABLE branch in the future, because the last thing you want to do is get stuck maintaining a EoL (End of Life) STABLE branch on your own (it's probably a waste of your resources). If you're an enthusiast, developer or just plain looking to get the most cutting edge features you can run CURRENT.

Hopefully this made sense to people not very familiar with how the development in FreeBSD works at a high level. If you're looking for more reading I would recommend at least this page in the handbook.

posted at: 15:18 | tags: | path: /entries/freebsd | permanent link to this entry