Chromium Patch Migration Case Study

This repository is a small, practical workflow for updating a Chromium-based browser fork while preserving custom client patches.

It focuses on the same work required in a real Chromium fork update:

• identifying the old Chromium base commit
• exporting and classifying custom patches
• checking whether patched files still exist in the target Chromium branch
• flagging high-risk conflicts before the rebase begins
• applying patches in controlled groups
• documenting Mac and Windows build notes
• creating a repeatable handoff process for future Chromium updates

The goal is not to replace engineering judgment. The goal is to make the update process predictable, reviewable, and easier to maintain over repeated Chromium upgrades.

What this proves

This project demonstrates a controlled approach to Chromium fork maintenance:

1. Clean separation between upstream Chromium and client-specific patches.
2. Patch-by-patch migration instead of copying old source files into a new Chromium tree.
3. Early detection of removed, moved, or refactored files.
4. Risk classification for branding, UI, build, platform, browser behavior, and networking changes.
5. Build and QA workflow for macOS and Windows.
6. Documentation suitable for a long-term update process.

Repository structure

scripts/
  chromium_patch_audit.py      Generate a patch inventory and conflict-risk report.
  export_patchset.sh           Export client commits into ordered patch files.
  apply_patchset.sh            Apply exported patches one by one with clear failure behavior.

docs/
  PATCH_MIGRATION_WORKFLOW.md  Step-by-step Chromium patch migration workflow.
  MAC_WINDOWS_BUILD_NOTES.md   Platform build notes for macOS and Windows.
  CLIENT_HANDOFF_SUMMARY.md    Short client-facing summary of the approach.

reports/
  Generated patch inventory reports go here.

Example usage

From inside a Chromium src checkout:

python3 scripts/chromium_patch_audit.py \
  --repo /path/to/chromium/src \
  --old-base OLD_CHROMIUM_BASE_SHA \
  --old-branch client/old-browser-branch \
  --target-base origin/main \
  --output reports/patch_inventory.md

Export the existing custom patches:

./scripts/export_patchset.sh \
  /path/to/chromium/src \
  OLD_CHROMIUM_BASE_SHA \
  client/old-browser-branch \
  ./patches

Apply them to a new Chromium branch:

./scripts/apply_patchset.sh \
  /path/to/chromium/src \
  ./patches

Recommended migration order

1. Build clean upstream Chromium first.
2. Create a dedicated client rebase branch.
3. Run the patch audit.
4. Migrate branding and build patches first.
5. Migrate UI and behavior patches in small groups.
6. Build after every small group.
7. Test Mac and Windows separately.
8. Keep a patch inventory and known-conflicts document for future updates.

Deliverables after a real migration

• updated Chromium branch
• ordered patch history
• macOS build notes
• Windows build notes
• patch inventory report
• known conflict notes
• manual QA checklist
• future update process