/electron-node-upgrade

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

Electron Node.js 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

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. For major version upgrades, patches that shim deprecated V8 APIs or backport upstream changes are often deletable because the new Node.js version already incorporates them — but verify before removing. 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/node/main` branch is created by automation to update Electron's Node.js dependency version in `DEPS`. No work has been done to handle breaking changes between the old and new versions.

There are two types of Node.js version updates:

• **Bumps** (patch/minor): Automated by `electron-roller[bot]` with commit title `chore: bump node to v{version}`. Trivial patch index updates are handled automatically by `patchup[bot]`. These often land cleanly, but may require manual patch fixes.
• **Major upgrades** (e.g., v22 → v24): Manual, large PRs with commit title `chore: upgrade Node.js to v{X}.{Y}.{Z}`. These typically involve deleting obsolete patches, adapting many others, and updating `@types/node` in `package.json`.

**Key directories:**

• Current directory: Electron repo (always run `e` commands here)
• `../third_party/electron_node`: Node.js repo (where patches apply)
• `patches/node/`: Patch files for Node.js
• `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 `../third_party/electron_node` repos. Stale recorded resolutions from a prior attempt can silently apply wrong merges. 2. **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. 3. **Look for the same roll on other branches**: fetch `roller/node/main` and any sibling `roller/node/{N}-x-y` branch for the same Node.js version. If they already carry fixes, reuse them verbatim (patch names, content, commit titles, `Ref:` lines) rather than re-deriving them. See "Reuse Fixes From Sibling Roller Branches" in `references/phase-one-commit-guidelines.md`.

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 `../third_party/electron_node` working directory
• Run `git am --continue` in `../third_party/electron_node`
• Repeat until all patches for that repo apply
• IMPORTANT: Once `git am --continue` succeeds you MUST run `e patches node` to export fixes
• Return to step 1

4. When `e sync --3` succeeds, run `e patches all` 5. **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 node repo) | | `e patches node` | Export commits from node repo to patch files | | `e patches all` | Export all patches from all targets | | `e patches node --commit-updates` | Export patches and auto-commit trivial changes | | `e patches --list-targets` | List targets and config paths |

Patch System Mental Model

patches/node/*.patch  →  [e sync --3]  →  ../third_party/electron_node commits
                      ←  [e patches]   ←

When to Edit Patches

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

Fix existing patches 99% of the time rather than creating new ones.

Patch Fixing Rules

1. **Preserve authorship**: Keep original author in TODO comments (from patch `From:` field) 2. **Never change TODO assignees**: `TODO(name)` must retain original name 3. **Update descriptions**: If upstream changed APIs or macros, update patch commit message to reflect current state 4. **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 resol