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.
npxskills add electron/electron--skill electron-chromium-upgradeLoading…
Run e sync --3 repeatedly, fixing patch conflicts as they arise, until it succeeds. Then export patches and commit changes atomically.
Linter Requirements:
{CL-Number}: {upstream CL original title} with Ref: {URL} in the body.chore: update patches with no body.Phase One is complete when:
e sync --3 exits with code 0 (no patch failures)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.
Never use 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 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.
git am --skipgit am --continueThe 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:
e commands here).. (parent): Chromium repo (where most patches apply)patches/: Patch files organized by targetdocs/development/patches.md: Patch system documentationRun these once at the start of each upgrade session:
git rerere clear in both the electron and .. repos. Stale recorded resolutions from a prior attempt can silently apply wrong merges..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.e sync --3 (the --3 flag enables 3-way merge, always required)git am --continue in affected repogit am --continue succeeds you MUST run e patches {target} to export fixese sync --3 succeeds, run e patches allreferences/phase-one-commit-guidelines.md NOW, then commit changes following those instructions exactly.| 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 |
patches/{target}/*.patch → [e sync --3] → target repo commits
← [e 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.
From: field)TODO(name) must retain original nameDCHECK → CHECK_IS_TEST), update patch commit message to reflect current stategit am --continue says "No changes — did you forget to use 'git add'?", do NOT run git am --skip and 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.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.
Linter Requirements:
{CL-Number}: {upstream CL original title} with Ref: {URL} in the body.chore: update patches with no body.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 launchesDo 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.
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. Chromium APIs frequently are renamed or refactored. In every case the code in Electron must be updated to account for the change in Chromium, strongly avoid making changes to the code in chromium to fix Electrons build.
Key directories:
e commands here).. (parent): Chromium repo (do not touch this code to fix build issues, just read it to obtain context)e build -k 999 -- --quiet (the --quiet flag suppresses per-target status lines, showing only errors and the final result)e build -t {target_that_failed}.o to build just the failed target we were specifically fixing
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.oreferences/phase-two-commit-guidelines.md NOW, then commit changes following those instructions exactly.git status in the electron repo
.patch files that only have index/hunk header changesgit commit -am "chore: update patches"e build succeeds, run e start --versiongit status
| Command | Purpose |
|---|---|
e build -k 999 -- --quiet | Build Electron, continue on errors, suppress status lines |
e build -t {target}.o | Build just one specific target to verify a fix |
e start --version | Validate Electron launches after successful build |
When the error is in a file that Electron patches (check with grep -l "filename" patches/chromium/*.patch):
/src/chrome/browser/...)cd .. # to chromium repo
git add <modified-file>
git commit --fixup=<original-patch-commit-hash>
GIT_SEQUENCE_EDITOR=: git rebase --autosquash --autostash -i <commit>^
e patches chromiumreferences/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 ref.
When the error is in Electron's own source code:
references/phase-one-commit-guidelines.mdreferences/phase-two-commit-guidelines.mdThis skill has additional reference files in references/:
Read these when referenced in the workflow steps.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).