/electron-chromium-upgrade

name: electron-chromium-upgrade
description: Guide for performing Chromium version upgrades in the Electron project. Use when working on the roller/chromium/main branch to fix patch conflicts during `e sync --3`. Covers the patch application workflow, conflict resolution, analyzing upstream Chromium changes, and proper commit formatting for patch fixes.

Electron Chromium Upgrade: Phase One

Summary

Run `e sync --3` repeatedly, fixing patch conflicts as they arise, until it succeeds. Then export patches and commit changes atomically.

Success Criteria

**Linter Requirements**:

• Code/patch edits: Title must be exactly `{CL-Number}: {upstream CL original title}` with `Ref: {URL}` in the body.
• Metadata-only patch updates (hashes/line numbers): Message must be exactly `chore: update patches` with no body.

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.

**CRITICAL** Never use `git am --skip` and then manually recreate a patch by making a new commit. This destroys the original patch's authorship, commit message, and position in the series. If `git am --continue` reports "No changes", investigate why — the changes were likely absorbed by a prior conflict resolution's 3-way merge. Present this situation to the user rather than skipping and recreating.

Context

The `roller/chromium/main` branch is created by automation to update Electron's Chromium dependency SHA. No work has been done to handle breaking changes between the old and new versions.

**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 config core.hooksPath` prints `.husky/_` and that `.husky/_/pre-commit` exists (husky does not use `.git/hooks/`). If not, run `yarn husky` to install it. The hook runs `lint-staged`, which handles clang-format for C++ files and runs `script/lint-roller-chromium-changes.mjs` on every commit.

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. **Regenerate the derived file lists.** Electron checks in lists that mirror Chromium's DEPS pins, and the gn-check CI job fails the roll on every platform if any of them is stale. The roller bot bumps `DEPS` without running the pre-commit hook that normally regenerates them, so run the generators by hand now (the gn-check job runs the `--check` form of each):

   node script/gen-hunspell-filenames.js   # filenames.hunspell.gni (from ../third_party/hunspell_dictionaries)
   node script/gen-libc++-filenames.js     # filenames.libcxx.gni / filenames.libcxxabi.gni
   node script/gen-siso-revision.js        # build/siso_revision (the gen_siso_revision sync hook usually did this already)
   node script/gen-filenames.mts --check   # fails only if lib/ or docs/api changed; regenerate without --check if it does

Then `git status` and commit each changed file on its own:

• `build/siso_revision` → `chore: update siso revision` (exact title, no body). CI builds siso from this file.
• `filenames.libcxx.gni` → `chore: update libc++ filenames` (exact title, no body, that file only).
• `filenames.hunspell.gni` (and `filenames.libcxxabi.gni`, which has no dedicated pattern) → a `{CL-Number}: {upstream CL original title}` commit with a `Ref:` line, where the CL is the upstream commit that moved the pin. Find it from the dep's new SHA in Chromium's `DEPS` (hunspell is `src/third_party/hunspell_dictionaries`, libc++abi is `src/third_party/libc++abi/src`):

     cd .. && git log --format='%h %s%n%(trailers:key=Reviewed-on,valueonly)' refs/patches/upstream-head -S<new-dep-sha> -- DEPS

6. **Read `references/phase-one-commit-guidelines.md` NOW**, then commit changes following those instructions exactly.

Commands Reference

| Command | Purpose | |---------|---------| | `e sync --3` | Clone deps and apply patches with 3-way merge | | `git am --continue` | Continue after resolving conflict (run in target repo) | | `e patches {target}` | Export commits from target repo to patch files | | `e patches all` | Export all patches from all targets | | `e patches {target} --commit-updates` | Export patches and auto-commit trivial changes | | `e patches --list-targets` | List targets and config paths |

Patch System Mental Model

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

When to Edit Patches

| Situation | Action | |-----------|--------| | During active `git am` conflict | Fix in target repo, then `git am --continue` | | Modifying patch outside conflict | Edit `.patch` file directly | | Creating new patch (rare, avoid) | Commi