Skip to content

CONCEPT Cited by 1 source

Feature-branch patch management

Definition

Feature-branch patch management is the discipline of tracking each internal patch against an upstream OSS project as a named Git feature branch rebased onto each new upstream release tag, rather than as stored patch files sequentially re-applied on each upgrade.

It is the alternative to the common .patch file approach used by many libwebrtc-based OSS projects:

Dimension Stored patch files Feature branches
Per-upgrade work Re-apply all patches to the new clean repo Merge forward each feature branch to the new tag
Git history Not preserved (patches reapply as single commits) Fully preserved per branch
Parallelism Serial (order matters) Highly parallel (branches independent)
Conflict resolution Manual, inside the patch tool Normal Git merge-conflict tools
Upstream submission Reformat patch to PR Submit the branch as-is
LLM-friendliness Poor (patch tool context limited) Good (branches have commit-level history)

Canonical disclosure

"Since we use a monorepo without widespread support for branches, we sought a way to track patches over time that would be continuously rebased on top of upstream… We had two choices here: We could track patch files checked into source control and reapply them one by one in the correct order, or we could track patches in a separate repository that supported branching. In the end we chose to go with tracking feature branches in a separate Git repository. One of the reasons for this was to establish a good pipeline for making it very easy to submit feature branches and fixes upstream." — Meta, 2026-04-09 WebRTC post (sources/2026-04-09-meta-escaping-the-fork-webrtc-modernization)

Branch naming scheme

Meta's scheme anchors every branch to the upstream release tag. For Chromium / libwebrtc:

base/7499                  Chromium M143's libwebrtc tag anchor
debug-tools/7499           "debug-tools" feature branched from base/7499
hw-av1-fixes/7499          "hw-av1-fixes" feature branched from base/7499
...

On upgrade to the next Chromium release (M145 ≈ tag 7559):

base/7559                                    the new tag anchor
debug-tools/7559 = merge(debug-tools/7499, base/7559)
hw-av1-fixes/7559 = merge(hw-av1-fixes/7499, base/7559)
...
r7559 = merge(all <feature>/7559 branches)   release candidate

Each <feature>/<tag> branch captures a single team-owned patch family. Each base/<tag> branch is the clean upstream anchor. The release candidate r<tag> is the sequenced merge of all feature branches, ready to be built, tested, and deployed.

Four named benefits

Meta's post enumerates why the external-Git-repo variant was chosen over storing patches in the monorepo:

  1. Parallelizable — feature branches rebase independently; N teams can upgrade in parallel.
  2. Preserves Git history — each branch's commit history stays intact across upgrades, so blame, bisect, and PR reviews work as normal.
  3. LLM-friendly — merge conflicts are expressible as "diff between these two commits"; Meta explicitly calls out "future improvements in LLM-driven auto-resolution of merge conflicts" as a motivating reason.
  4. Upstream-submit-ready — a feature branch can be submitted upstream as-is, no patch-file repackaging.

Operational prerequisites

The scheme requires:

  • Branch-capable Git hosting — Meta's internal monorepo lacks this at the scale needed, which is why Solution 2 is in a separate Git repo alongside the monorepo. See patterns/external-feature-branch-repo-for-monorepo-patches.
  • Upstream tooling reusability — basing branches on the upstream project's own Git repo (e.g. libwebrtc's) means you can reuse the upstream's existing build / test / submission tools. Meta gets gn, gclient, and git cl for free.
  • A tag-anchored discipline — every branch name encodes the upstream release tag, making the upgrade-target unambiguous.

Relationship to upstream submission

The architecture is deliberately aligned with eventual upstream contribution. Because each branch is already formatted as normal Git commits against upstream's own tree, submitting it upstream is a matter of pushing the branch to the upstream remote and opening a review. This closes the loop with patterns/upstream-the-fix: residual internal patches kept this way are submit-ready whenever the organization decides they should be upstreamed.

Seen in

Last updated · 319 distilled / 1,201 read