Electron Chromium Upgrade: Phase One

Summary

Run

e sync --3

Success Criteria

Phase One is complete when:

• e sync --3

  exits with code 0 (no patch failures)
• All changes are committed per the commit guidelines

Do not stop until these criteria are met.

CRITICAL Do not delete or skip patches unless 100% certain the patch is no longer needed. Complicated conflicts or hard to resolve issues should be presented to the user after you have exhausted all other options. Do not delete the patch just because you can't solve it.

Context

The

roller/chromium/main

Key directories:

• Current directory: Electron repo (always run

  e

  commands here)

• ..

  (parent): Chromium repo (where most patches apply)

• patches/

  : Patch files organized by target

• docs/development/patches.md

  : Patch system documentation

Pre-flight Checks

Run these once at the start of each upgrade session:

1. Clear rerere cache (if enabled):

   git rerere clear

   in both the electron and

   ..

   repos. Stale recorded resolutions from a prior attempt can silently apply wrong merges.
2. Ensure pre-commit hooks are installed: Check that

   .git/hooks/pre-commit

   exists. If not, run

   yarn husky

   to install it. The hook runs

   lint-staged

   which handles clang-format for C++ files.

Workflow

1. Run

   e sync --3

   (the

   --3

   flag enables 3-way merge, always required)
2. If succeeds → skip to step 5
3. If patch fails:
   • Identify target repo and patch from error output
   • Analyze failure (see references/patch-analysis.md)
   • Fix conflict in target repo's working directory
   • Run

     git am --continue

     in affected repo
   • Repeat until all patches for that repo apply
   • IMPORTANT: Once

     git am --continue

     succeeds you MUST run

     e patches {target}

     to export fixes
   • Return to step 1
4. When

   e sync --3

   succeeds, run

   e patches all

5. Read

   references/phase-one-commit-guidelines.md

   NOW, then commit changes following those instructions exactly.

Commands Reference

e sync --3

git am --continue

e patches {target}

e patches all

e patches {target} --commit-updates

e patches --list-targets

Patch System Mental Model

patches/{target}/*.patch  →  [e sync --3]  →  target repo commits
                          ←  [e patches]   ←

When to Edit Patches

git am

git am --continue

.patch

e patches {target}

Fix existing patches 99% of the time rather than creating new ones.

Patch Fixing Rules

1. Preserve authorship: Keep original author in TODO comments (from patch

   From:

   field)
2. Never change TODO assignees:

   TODO(name)

   must retain original name
3. Update descriptions: If upstream changed (e.g.,

   DCHECK

   →

   CHECK_IS_TEST

   ), update patch commit message to reflect current state

Electron Chromium Upgrade: Phase Two

Summary

Run

e build -k 999 -- --quiet

e start --version

Run Phase Two immediately after Phase One is complete.

Success Criteria

Phase Two is complete when:

• e build -k 999 -- --quiet

  exits with code 0 (no build failures)

• e start --version

  has been run to check Electron launches
• All changes are committed per the commit guidelines

Do not stop until these criteria are met. Do not delete code or features, never comment out code in order to take short cut. Make all existing code, logic and intention work.

Context

The

roller/chromium/main

Key directories:

• Current directory: Electron repo (always run

  e

  commands here)

• ..

  (parent): Chromium repo (do not touch this code to fix build issues, just read it to obtain context)

Workflow

1. Run

   e build -k 999 -- --quiet

   (the

   --quiet

   flag suppresses per-target status lines, showing only errors and the final result)
2. If succeeds → skip to step 6
3. If build fails:
   • Identify underlying file in "electron" from the compilation error message
   • Analyze failure
   • Fix build issue by adapting Electron's code for the change in Chromium
   • Run

     e build -t {target_that_failed}.o

     to build just the failed target we were specifically fixing
     • You can identify the target_that_failed from the failure line in the build log. E.g.

       FAILED: 2e506007-8d5d-4f38-bdd1-b5cd77999a77 "./obj/electron/chromium_src/chrome/process_singleton_posix.o" CXX obj/electron/chromium_src/chrome/process_singleton_posix.o

       the target name is

       obj/electron/chromium_src/chrome/process_singleton_posix.o

   • Read

     references/phase-two-commit-guidelines.md

     NOW, then commit changes following those instructions exactly.
   • Return to step 1
4. CRITICAL: After ANY commit (especially patch commits), immediately run

   git status

   in the electron repo
   • Look for other modified

     .patch

     files that only have index/hunk header changes
   • These are dependent patches affected by your fix
   • Commit them immediately with:

     git commit -am "chore: update patches (trivial only)"

5. Return to step 1
6. When

   e build

   succeeds, run

   e start --version

7. Check if you have any pending changes in the Chromium repo by running

   git status

   • If you have changes follow the instructions below in "A. Patch Fixes" to correctly commit those modifications into the appropriate patch file

Commands Reference

e build -k 999 -- --quiet

e build -t {target}.o

e start --version

Two Types of Build Fixes

A. Patch Fixes (for files in chromium_src or patched Chromium files)

When the error is in a file that Electron patches (check with

grep -l "filename" patches/chromium/*.patch

1. Edit the file in the Chromium source tree (e.g.,

   /src/chrome/browser/...

   )
2. Create a fixup commit targeting the original patch commit:

   cd ..  # to chromium repo
   git add <modified-file>
   git commit --fixup=<original-patch-commit-hash>
   GIT_SEQUENCE_EDITOR=: git rebase --autosquash --autostash -i <commit>^
   

3. Export the updated patch:

   e patches chromium

4. Commit the updated patch file following

   references/phase-one-commit-guidelines.md

   .

To find the original patch commit to fixup:

git log --oneline | grep -i "keyword from patch name"

The base commit for rebase is the Chromium commit before patches were applied. Find it by checking the

refs/patches/upstream-head

B. Electron Code Fixes (for files in shell/, electron/, etc.)

When the error is in Electron's own source code:

1. Edit files directly in the electron repo
2. Commit directly (no patch export needed)

Critical: Read Before Committing

• Before ANY Phase One commits: Read

  references/phase-one-commit-guidelines.md

• Before ANY Phase Two commits: Read

  references/phase-two-commit-guidelines.md

Skill Directory Structure

This skill has additional reference files in

references/

• patch-analysis.md - How to analyze patch failures
• phase-one-commit-guidelines.md - Commit format for Phase One
• phase-two-commit-guidelines.md - Commit format for Phase Two

Read these when referenced in the workflow steps.