FreeBSD Release Engineering: -CURRENT, -STABLE, and Shipping Releases

FreeBSD’s development model separates “where new code lands” from “what you’d actually run in production” through a small number of long-lived branches with very different stability guarantees. Understanding the branch names — -CURRENT, -STABLE, and numbered releases — is the difference between knowingly running bleeding-edge code and accidentally doing so.

-CURRENT: the trunk

main (historically referred to by its version suffix as -CURRENT, e.g. 15.0-CURRENT) is where active kernel and userland development happens first. Every new feature, every architectural change, lands here before anywhere else.

git clone -b main https://git.FreeBSD.org/src.git /usr/src

-CURRENT carries no stability guarantee at all — it can fail to build, boot, or behave correctly on any given day, and is explicitly intended for developers and testers comfortable filing bug reports, not production use. Its value is precisely that it surfaces problems early, against a wide variety of hardware and workloads, well before that code reaches a branch anyone depends on.

-STABLE: the maintained branch

Periodically, a stable branch is cut from main — for example stable/14. From that point on, stable/14 and main diverge: new feature development continues on main, while stable/14 only receives fixes that have already proven themselves there, backported deliberately.

git clone -b stable/14 https://git.FreeBSD.org/src.git /usr/src

This is the branch model’s core mechanism for de-risking change: nothing reaches -STABLE without first existing on -CURRENT, and typically without having survived some amount of real-world exposure there. Running -STABLE means tracking ongoing development, but with a substantially higher bar for what’s allowed to land.

Releases: point-in-time snapshots with support

A release — 14.2-RELEASE, for instance — is a tagged, fixed snapshot of a stable branch at a specific point, built, tested, and published as installable images (ISO, VM images, cloud provider images). Once tagged, a release doesn’t change; it receives only security and critical errata fixes on its own branch, delivered as periodic updates:

freebsd-version
freebsd-update fetch
freebsd-update install

freebsd-update is how most production systems stay current within a release’s support window without a source rebuild — it distributes pre-built binary patches for security advisories and errata notices, tracked at https://www.freebsd.org/security/.

The relationship between the three

The flow is strictly one-directional in terms of stability guarantees: code is written against main, proven there, selectively backported to the relevant stable/NN branch, and periodically that stable branch is snapshotted and tagged as a new point release.

main (-CURRENT)
  │  new features land here first
  ▼
stable/14 (-STABLE)
  │  only vetted fixes are merged back
  ▼
14.2-RELEASE
  │  tagged, frozen, security/errata patched only

A given machine’s uname -r tells you exactly where it sits in this model — 14.2-RELEASE-p3 (a released, patched version), 14-STABLE (tracking the stable branch’s ongoing tip), or 15.0-CURRENT (tracking trunk directly).

Choosing a branch to run

For production systems, tracking a numbered -RELEASE and applying freebsd-update patches is almost always the right default — it gets security fixes without absorbing unrelated change. Tracking -STABLE from source makes sense when you need a fix or feature that hasn’t reached a release yet but has already been vetted on the stable branch, and are willing to rebuild world and kernel periodically to stay current. -CURRENT belongs on development and testing machines whose purpose is explicitly to catch problems before they reach anyone else — treating it as a production branch inverts the entire point of the model.

Where the ports tree fits in

It’s worth noting this branch structure governs the base system (kernel, core userland) specifically — the ports tree has its own, faster-moving release cadence (quarterly branches for those who want package stability, plus a continuously updated main for ports) that’s largely independent of which base system branch you’re running. A 14.2-RELEASE system can happily track either the latest ports or a quarterly ports branch, since pkg’s ABI compatibility is tied to the base system’s major version, not its exact patch level.