electron-chromium-upgrade
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.
modem-dev · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add modem-dev/ossrules --skill electron-chromium-upgradeAbout this skill
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}withRef: {URL}in the body. - Metadata-only patch updates (hashes/line numbers): Message must be exactly
chore: update patcheswith no body.
Phase One is complete when:
e sync --3exits 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
ecommands here) ..(parent): Chromium repo (where most patches apply)patches/: Patch files organized by targetdocs/development/patches.md: Patch system documentation
Pre-flight Checks
Run these once at the start of each upgrade session:
- Clear rerere cache (if enabled):
git rerere clearin both the electron and..repos. Stale recorded resolutions from a prior attempt can silently apply wrong merges. - Ensure pre-commit hooks are installed: Check that
.git/hooks/pre-commitexists. If not, runyarn huskyto install it. The hook runslint-stagedwhich handles clang-format for C++ files.
Workflow
- Run
e sync --3(the--3flag enables 3-way merge, always required) - If succeeds → skip to step 5
- 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 --continuein affected repo - Repeat until all patches for that repo apply
- IMPORTANT: Once
git am --continuesucceeds you MUST rune patches {target}to export fixes - Return to step 1
- When
e sync --3succeeds, rune patches all - Read
references/phase-one-commit-guidelines.mdNOW, 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) | Commit in target repo, then e patches {target} |
Fix existing patches 99% of the time rather than creating new ones.
Patch Fixing Rules
- Preserve authorship: Keep original author in TODO comments (from patch
From:field) - Never change TODO assignees:
TODO(name)must retain original name - Update descriptions: If upstream changed (e.g.,
DCHECK→CHECK_IS_TEST), update patch commit message to reflect current state - Never skip-and-recreate a patch: If
git am --continuesays "No changes — did you forget to use 'git add'?", do NOT rungit am --skipand create a replacement commit. The patch's changes were already absorbed by a prior 3-way merge resolution. This means an earlier conflict resolution pulled in too many changes. Present the situation to the user for guidance — the correct fix may require re-doing an earlier resolution more carefully to keep each patch's changes separate.
Electron Chromium Upgrade: Phase Two
Summary
Run e build -k 999 -- --quiet repeatedly, fixing build issues as they arise, until it succeeds. Then run e start --version to validate Electron launches and commit changes atomically.
Run Phase Two immediately after Phase One is complete.
Success Criteria
Linter Requirements:
- Code/patch edits: Title must be exactly
{CL-Number}: {upstream CL original title}withRef: {URL}in the body. - Metadata-only patch updates (hashes/line numbers): Message must be exactly
chore: update patcheswith no body.
Phase Two is complete when:
e build -k 999 -- --quietexits with code 0 (no build failures)e start --versionhas 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, neve
Read the complete source ↗