6# Electron Chromium Upgrade: Phase One
7
8## Summary
9
10Run e sync --3 repeatedly, fixing patch conflicts as they arise, until it succeeds. Then export patches and commit changes atomically.
11
12## Success Criteria
13
14**Linter Requirements**:
15- Code/patch edits: Title must be exactly {CL-Number}: {upstream CL original title} with Ref: {URL} in the body.
16- Metadata-only patch updates (hashes/line numbers): Message must be exactly chore: update patches with no body.
17
18Phase One is complete when:
19- e sync --3 exits with code 0 (no patch failures)
20- All changes are committed per the commit guidelines
21
22Do not stop until these criteria are met.
23
24**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.
25
26**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.
27
28## Context
29
30The 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.
31
32**Key directories:**
33- Current directory: Electron repo (always run e commands here)
34- .. (parent): Chromium repo (where most patches apply)
35- patches/: Patch files organized by target
36- docs/development/patches.md: Patch system documentation
37
38## Pre-flight Checks
39
40Run these once at the start of each upgrade session:
41
421. **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.
432. **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.
44
45## Workflow
46
471. Run e sync --3 (the --3 flag enables 3-way merge, always required)
482. If succeeds → skip to step 5
493. If patch fails:
50 - Identify target repo and patch from error output
51 - Analyze failure (see references/patch-analysis.md)
52 - Fix conflict in target repo's working directory
53 - Run git am --continue in affected repo
54 - Repeat until all patches for that repo apply
55 - IMPORTANT: Once git am --continue succeeds you MUST run e patches {target} to export fixes
56 - Return to step 1
574. When e sync --3 succeeds, run e patches all
585. **Read references/phase-one-commit-guidelines.md NOW**, then commit changes following those instructions exactly.
59
60## Commands Reference
61
62| Command | Purpose |
63|---------|---------|
64| e sync --3 | Clone deps and apply patches with 3-way merge |
65| git am --continue | Continue after resolving conflict (run in target repo) |
66| e patches {target} | Export commits from target repo to patch files |
67| e patches all | Export all patches from all targets |
68| e patches {target} --commit-updates | Export patches and auto-commit trivial changes |
69| e patches --list-targets | List targets and config paths |
70
71## Patch System Mental Model
72
73```
74patches/{target}/*.patch → [e sync --3] → target repo commits
75 ← [e patches] ←
76```
77
78## When to Edit Patches
79
80| Situation | Action |
81|-----------|--------|
82| During active git am conflict | Fix in target repo, then git am --continue |
83| Modifying patch outside conflict | Edit .patch file directly |
84| Creating new patch (rare, avoid) | Commit in target repo, then e patches {target} |
85
86Fix existing patches 99% of the time rather than creating new ones.
87
88## Patch Fixing Rules
89
901. **Preserve authorship**: Keep original author in TODO comments (from patch From: field)
912. **Never change TODO assignees**: TODO(name) must retain original name
923. **Update descriptions**: If upstream changed (e.g., DCHECK → CHECK_IS_TEST), update patch commit message to reflect current state
934. **Never skip-and-recreate a patch**: If git 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.
94
95# Electron Chromium Upgrade: Phase Two
96
97## Summary
98
99Run 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.
100
101Run Phase Two immediately after Phase One is complete.
102
103## Success Criteria
104
105**Linter Requirements**:
106- Code/patch edits: Title must be exactly {CL-Number}: {upstream CL original title} with Ref: {URL} in the body.
107- Metadata-only patch updates (hashes/line numbers): Message must be exactly chore: update patches with no body.
108
109Phase Two is complete when:
110- e build -k 999 -- --quiet exits with code 0 (no build failures)
111- e start --version has been run to check Electron launches
112- All changes are committed per the commit guidelines
113
114Do 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.
115
116## Context
117
118The 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.
119
120**Key directories:**
121- Current directory: Electron repo (always run e commands here)
122- .. (parent): Chromium repo (do not touch this code to fix build issues, just read it to obtain context)
123
124## Workflow
125
1261. Run e build -k 999 -- --quiet (the --quiet flag suppresses per-target status lines, showing only errors and the final result)
1272. If succeeds → skip to step 6
1283. If build fails:
129 - Identify underlying file in "electron" from the compilation error message
130 - Analyze failure
131 - Fix build issue by adapting Electron's code for the change in Chromium
132 - Run e build -t {target_that_failed}.o to build just the failed target we were specifically fixing
133 - 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
134 - **Read references/phase-two-commit-guidelines.md NOW**, then commit changes following those instructions exactly.
135 - Return to step 1
1364. **CRITICAL**: After ANY commit (especially patch commits), immediately run git status in the electron repo
137 - Look for other modified .patch files that only have index/hunk header changes
138 - These are dependent patches affected by your fix
139 - Commit them immediately with: git commit -am "chore: update patches"
1405. Return to step 1
1416. When e build succeeds, run e start --version
1427. Check if you have any pending changes in the Chromium repo by running git status
143 - If you have changes follow the instructions below in "A. Patch Fixes" to correctly commit those modifications into the appropriate patch file
1448. Final commit self-check: run git log --format='%h %B' over the commits this upgrade added (everything since the chore: bump chromium in DEPS commit) and verify that each upstream CL is referenced by exactly one non-fixup commit — full messages, not just titles, since Ref: lines live in commit bodies. If a CL appears in more than one non-fixup commit, consolidate with git commit --fixup + autosquash rebase per references/phase-two-commit-guidelines.md
145
146## Commands Reference
147
148| Command | Purpose |
149|---------|---------|
150| e build -k 999 -- --quiet | Build Electron, continue on errors, suppress status lines |
151| e build -t {target}.o | Build just one specific target to verify a fix |
152| e start --version | Validate Electron launches after successful build |
153
154## Two Types of Build Fixes
155
156### A. Patch Fixes (for files in chromium_src or patched Chromium files)
157
158When the error is in a file that Electron patches (check with grep -l "filename" patches/chromium/*.patch):
159
1601. Edit the file in the Chromium source tree (e.g., /src/chrome/browser/...)
1612. Create a fixup commit targeting the original patch commit:
162 ```bash
163 cd .. # to chromium repo
164 git add <modified-file>
165 git commit --fixup=<original-patch-commit-hash>
166 GIT_SEQUENCE_EDITOR=: git rebase --autosquash --autostash -i <commit>^
167 ```
1683. Export the updated patch: e patches chromium
1694. Commit the updated patch file following references/phase-one-commit-guidelines.md.
170
171To find the original patch commit to fixup: git log --oneline | grep -i "keyword from patch name"
172
173The base commit for rebase is the Chromium commit before patches were applied. Find it by checking the refs/patches/upstream-head ref.
174
175### B. Electron Code Fixes (for files in shell/, electron/, etc.)
176
177When the error is in Electron's own source code:
178
1791. Edit files directly in the electron repo
1802. Commit directly (no patch export needed)
181
182# Critical: Read Before Committing
183
184- Before ANY Phase One commits: Read references/phase-one-commit-guidelines.md
185- Before ANY Phase Two commits: Read references/phase-two-commit-guidelines.md
186
187# Skill Directory Structure
188This skill has additional reference files in references/:
189- patch-analysis.md - How to analyze patch failures
190- phase-one-commit-guidelines.md - Commit format for Phase One
191- phase-two-commit-guidelines.md - Commit format for Phase Two
192
193Read these when referenced in the workflow steps.
194