Chromium Fork Workflow

This chapter describes the current Chromium fork workflow for CBF contributors.

ADR 0009 is the normative rationale for this workflow:

• docs/decisions/0009-separate-chromium-integration-patches-from-cbf-implementation-layer.md

1. Two-layer model

CBF manages Chromium fork state as two separate layers:

• implementation layer: the CBF-owned browser-process module under chrome/browser/cbf/**
• integration layer: the patch queue that wires CBF into existing Chromium code outside that subtree

Repository-side source of truth:

• implementation layer: chromium/cbf/chrome/browser/cbf/**
• integration layer: chromium/patches/cbf/**

Working tree during development:

• implementation edits: chromium/src/chrome/browser/cbf/**
• integration edits: chromium/src/** excluding chromium/src/chrome/browser/cbf/**

chrome/browser/cbf/** is mechanically excluded from the integration patch queue. Do not export that subtree as part of chromium/patches/cbf/**.

2. Apply, export, and clean

The tooling flow is:

uv run tool apply
uv run tool export
uv run tool clean
uv run tool git <...args>
uv run tool commit -m "<message>"

uv run tool apply performs two steps:

1. copy chromium/cbf/chrome/browser/cbf/** into chromium/src/chrome/browser/cbf/**
2. apply the integration patch queue from chromium/patches/cbf/** with git am

uv run tool export performs two steps:

1. copy chromium/src/chrome/browser/cbf/** back into chromium/cbf/chrome/browser/cbf/**
2. export the integration patch queue from chromium/src while excluding chromium/src/chrome/browser/cbf/**

uv run tool clean resets chromium/src back to base_commit and removes untracked files, including the applied implementation layer.

The implementation sync uses full mirror semantics:

• implementation export removes files from chromium/cbf/** that were deleted in chromium/src/chrome/browser/cbf/**
• implementation apply removes files from chromium/src/chrome/browser/cbf/** that are no longer present in chromium/cbf/**

3. Integration patch policy

Integration patches are curated for maintenance, not chronology.

Required rules:

• keep one primary integration responsibility per patch
• keep each patch locally understandable at the point where it is introduced
• let later patches extend earlier ones instead of redefining their primary meaning
• do not leave implementation-layer changes in the integration patch queue
• do not export fixup! or squash! commits

Examples of valid integration seams:

• build and target wiring
• startup and bootstrap plumbing
• lifecycle and observer hook points
• permission, dialog, and download integration hooks
• extension, popup, and settings integration hooks
• shutdown and crash hardening outside chrome/browser/cbf/**

Patch filenames are lexical by number. Use short imperative English subjects and keep the series buildable.

4. Day-to-day development

Implementation-layer work is still edited in chromium/src/chrome/browser/cbf/** for normal Chromium development. When you want to persist those changes in the CBF repository, run uv run tool export.

Integration-layer work is committed in chromium/src and exported into chromium/patches/cbf/**. The exporter will reject integration export when the commit range contains:

• committed changes under chrome/browser/cbf/**
• remaining fixup! or squash! commits

That guardrail is intentional. Curate the integration commit stack before exporting patches.

5. Build and test targets

Use autoninja from chromium/src or the repository helper:

autoninja -C out/Default chrome
autoninja -C out/Default cbf_bridge

uv run tool build -t chrome -t cbf_bridge

Relevant targets:

• chrome: Chromium-fork browser target
• cbf_bridge: bridge shared library used by cbf-chrome-sys
• cbf_tests, browser_tests, unit_tests: Chromium-side test targets

6. Reconstruction flow

A fresh Chromium checkout is reconstructed in this order:

1. check out base_commit
2. run uv run tool apply
3. build the required targets

That flow restores chrome/browser/cbf/** from chromium/cbf/** first and then reapplies the integration patch series from chromium/patches/cbf/**.