Electron Chromium Upgrade Phase One success criteria
Phase One is complete when: (1) `e sync --3` exits with code 0 (no patch failures), and (2) all changes are committed per commit guidelines. Do not stop until these criteria are met.
Electron · Tutorial · all subjects
versioning & release management
27 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Phase One patch commit message format for code/patch edits
Code or patch edits must have a commit title in the exact format: `{CL-Number}: {upstream CL original title}` with `Ref: {URL}` in the commit body.
Phase One patch commit message format for metadata-only updates
Metadata-only patch updates (hashes/line numbers) must have a commit message that is exactly `chore: update patches` with no body text.
Never delete patches during Chromium upgrade
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 exhausting all other options. Do not delete the patch just because you cannot solve it.
Phase One pre-flight check: clear rerere cache
Clear the rerere cache before starting an upgrade session by running `git rerere clear` in both the electron and parent (chromium) repos. Stale recorded resolutions from a prior attempt can silently apply wrong merges.
Phase One pre-flight check: ensure pre-commit hooks installed
Ensure pre-commit hooks are installed by checking 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.
Phase One workflow: e sync --3 with 3-way merge required
Always run `e sync --3` with the `--3` flag to enable 3-way merge. Run it repeatedly, fixing patch conflicts as they arise. After `git am --continue` succeeds for any patch, immediately run `e patches {target}` to export the fixes before returning to step 1.
Phase One workflow: export all patches before committing
When `e sync --3` succeeds, run `e patches all` to export all patches from all targets before committing changes.
Patch system mental model: bidirectional sync
Patches flow from `patches/{target}/*.patch` to target repo commits via `e sync --3`, and back from target repo commits to patch files via `e patches`.
Patch fixing rule: preserve authorship
Keep the original author in TODO comments from the patch `From:` field when fixing patches.
Patch fixing rule: never change TODO assignees
`TODO(name)` must retain the original name and never be changed when fixing patches.
Patch fixing rule: update descriptions if upstream changed
If upstream changes (e.g., `DCHECK` → `CHECK_IS_TEST`), update the patch commit message to reflect the current state.
Phase Two build command with quiet flag
Run `e build -k 999 -- --quiet` to build Electron while continuing on errors and suppressing per-target status lines, showing only errors and the final result.
Phase Two: fix build issues by adapting Electron code, not Chromium
When fixing Phase Two build issues, adapt Electron's code for changes in Chromium rather than making changes to the code in the Chromium repo. Strongly avoid modifying Chromium code to fix Electron's build.
Phase Two: build specific target after fixing
After fixing a build issue, run `e build -t {target_that_failed}.o` to build just the failed target to verify the fix. The target name can be identified from the failure line in the build log, e.g., `obj/electron/chromium_src/chrome/process_singleton_posix.o`.
Phase Two: check git status after commits for dependent patches
After ANY commit in Phase Two (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"`
Phase Two: validate Electron launches
When `e build` succeeds, run `e start --version` to validate that Electron launches correctly.
Phase Two: check for pending Chromium changes
After `e start --version` succeeds, check for any pending changes in the Chromium repo by running `git status`. If changes exist, follow the patch fixes instructions to correctly commit those modifications into the appropriate patch file.
Phase Two: final commit verification of upstream CL references
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. If a CL appears in more than one non-fixup commit, consolidate with `git commit --fixup` plus autosquash rebase.
Phase Two patch fix workflow: fixup commit with autosquash
When fixing a file that Electron patches: (1) Edit the file in the Chromium source tree, (2) Create a fixup commit: `git add <modified-file>` then `git commit --fixup=<original-patch-commit-hash>`, (3) Rebase with autosquash: `GIT_SEQUENCE_EDITOR=: git rebase --autosquash --autostash -i <commit>^`, (4) Export the updated patch: `e patches chromium`, (5) Commit the updated patch file.
Phase Two patch fix: finding the original patch commit to fixup
To find the original patch commit to fixup, run `git log --oneline | grep -i "keyword from patch name"`. The base commit for rebase is the Chromium commit before patches were applied, found by checking the `refs/patches/upstream-head` ref.
Phase Two Electron code fixes: direct commit, no patch export
When the build error is in Electron's own source code (files in shell/, electron/, etc.), edit files directly in the electron repo and commit directly — no patch export is needed.
Chromium upgrade: never delete code or comment out for shortcuts
Do not delete code or features, and never comment out code in order to take short cuts. Make all existing code, logic and intention work during Chromium upgrades.
e patches command with target parameter
`e patches {target}` exports commits from the specified target repo to patch files.
e patches all command
`e patches all` exports all patches from all targets.
e patches with commit-updates flag
`e patches {target} --commit-updates` exports patches and auto-commits trivial changes.
e patches --list-targets command
`e patches --list-targets` lists targets and their config paths.