Trunk-Based Development and Feature Flags: A Practical Guide

Every software team has to decide how people's changes come together. One common approach gives each feature its own branch, which lives for days or weeks and is merged when the feature is finished. Another keeps almost everyone working on a single shared line of code and merges small changes many times a day. The second approach is called trunk-based development, and it usually travels with a companion technique: feature flags.

These two ideas solve a real tension. Teams want to integrate often, so problems surface while they are small, but they cannot finish every feature in a few hours. Trunk-based development handles the integration; feature flags let unfinished work sit safely in the shared code without being switched on for users.

This guide explains both practices, how they work together, and the costs that are easy to underestimate. If you are new to continuous integration, our guide Continuous Integration and Delivery Explained is a useful first read.

What Trunk-Based Development Means

The reference site trunkbaseddevelopment.com, maintained by Paul Hammant, defines it as a branching model "where developers collaborate on code in a single branch called 'trunk'" and resist pressure to create other long-lived development branches by using documented techniques. The site notes the model is not new; it says it has been a lesser-known branching model of choice since the mid-1990s.

DORA, the long-running research program on software delivery, describes the difference in terms of scope. Feature branches typically involve multiple developers and take days or even weeks of work. Branches in trunk-based development typically last no more than a few hours. DORA's guidance lists three markers:

• Three or fewer active branches in the application's code repository.
• Branches merged to trunk at least once a day.
• No code freezes and no integration phases.

DORA reports that its research found teams following these practices achieve higher levels of software delivery and operational performance.

Short-Lived Branches and Pull Requests

Trunk-based development does not forbid branches. It forbids long ones. Teams can commit directly to the trunk, which tends to suit very small teams, or use short-lived feature branches with pull requests and code review.

The trunk-based development site gives two simple rules for short-lived branches. First, a branch should last a couple of days at most; any longer and it risks becoming a long-lived feature branch, which the site calls the antithesis of trunk-based development. Second, a branch should belong to one developer or one pair, and that person or pair should have only one such branch in flight at a time.

Code review is a common bottleneck. DORA notes that when review is laborious and takes hours or days, developers batch up changes, reviews get larger, and defects are more likely to slip through. It recommends synchronous review, asking a teammate to review right away rather than submitting a request and moving on, and points out that pair programming means the code has already been reviewed by a second person. Our guide to code review best practices for healthy teams goes deeper.

Keeping the Trunk Releasable

If everyone integrates into one branch, a broken trunk stops everyone. Three habits protect it.

1. Test before you push. DORA stresses running automated tests against changes before committing, and the trunk-based development site describes developers running a full build, including unit and integration tests, on their own workstation first.
2. Fix or revert fast. DORA's guidance says that if the build fails, developers should stop and fix it immediately, or revert the change if it cannot be fixed in a few minutes.
3. Handle big changes in small steps. For a change that will take days, the site describes branch by abstraction: introduce an abstraction around the code to be replaced, build the new implementation behind it while it stays switched off, flip the switch on, then remove the old implementation and finally the abstraction. No commit along the way is allowed to break the build.

What about releases? Teams that release often may release straight from the trunk. Teams on a slower cadence often cut a release branch shortly before a release. The site's guidance is to fix production bugs on the trunk first, with a test, and then cherry-pick the fix to the release branch, never the other way around, so a fix cannot be forgotten and reappear later as a regression.

Feature Flags: Separating Deployment From Release

A feature flag, also called a feature toggle, lets you change what a system does without deploying new code. OpenFeature, an open specification that is a Cloud Native Computing Foundation incubating project, puts it simply: in the most basic case, a feature flag is "an if/else statement that can be controlled at runtime."

Pete Hodgson's article "Feature Toggles (aka Feature Flags)," published on Martin Fowler's site, groups flags into four categories, each with a different expected lifetime:

• Release toggles hide incomplete work so the trunk can be deployed at any time. Hodgson describes them as transitional and says they should generally not stick around much longer than a week or two, although product-focused ones may last longer.
• Experiment toggles route groups of users down different code paths for A/B or multivariate testing.
• Ops toggles let operators disable or degrade a feature quickly, for example a resource-heavy page panel under unusual load. Most are short-lived, but a few may serve as long-lived kill switches.
• Permissioning toggles turn features on for specific users, such as internal testers, beta users or paying customers, and can last for years.

Release toggles are the ones that make trunk-based development practical. Hodgson describes using them as the most common way to apply the continuous delivery principle of separating feature release from code deployment.

The Hidden Costs of Flags

Flags are cheap to add and easy to forget. Hodgson warns that they come with a carrying cost, adding conditional logic to the code and a significant testing burden, and that "savvy teams" treat flags as inventory to keep as low as possible. Practices he describes include:

• Adding a removal task to the backlog whenever a release toggle is created.
• Putting expiration dates on toggles, and in some teams "time bombs" that fail a test if a flag outlives its date.
• Limiting the total number of flags allowed at once.

Testing needs thought too. A system with flags can run in many configurations, but Hodgson notes you do not need to test every combination, since most flags do not interact. He recommends testing the configuration expected in production plus any flags you intend to turn on, the fallback configuration with those flags off, and, for many teams, all flags on. That advice depends on a convention: existing behavior when a flag is off, new behavior when it is on.

A Hypothetical Example

Imagine a team of five rebuilding the checkout page of an online store. Instead of a six-week feature branch, they add a release toggle that is off in production. Each developer merges small changes to the trunk at least daily, with tests running before every merge. The team turns the flag on in a test environment, then for internal staff, then for everyone. Two weeks after full rollout, a backlog item they created on day one reminds them to delete the flag and the old checkout code.

Key takeaways

• Trunk-based development means integrating small changes into one shared branch at least daily and avoiding long-lived branches.
• DORA lists three markers: three or fewer active branches, daily merges to trunk and no code freezes or integration phases.
• Short-lived branches, fast synchronous review, pre-push testing and branch by abstraction keep the trunk releasable.
• Feature flags separate deployment from release; release toggles let unfinished work live safely in the trunk.
• Treat flags as inventory with a carrying cost: plan their removal and test both the on and off states.

Sources

• Paul Hammant, Trunk Based Development
• Paul Hammant, Short-Lived Feature Branches
• Paul Hammant, Branch by Abstraction
• Paul Hammant, Branch for Release
• DORA, Trunk-based development
• Pete Hodgson, Feature Toggles (aka Feature Flags), martinfowler.com (2016, revised 2017)
• OpenFeature, Introduction