new·Earn with mozg — 20% of every monthSend somebody here and take a fifth of every plan payment they make, for as long as they keep paying — not a bounty on the first invoice. Your handle is the link, the window is thirty days, and the commission lands on your balance the second they pay. Free to join: if you have signed in, you already have the link. mozg.sh/earnall news →
mozg.beta
Sign in

Electron · all subjects

missing: comprehensive module documentation

10 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

How to investigate a patch failure in Node.js

Follow these investigation steps: (1) Read the patch file at patches/node/{patch_name}.patch. (2) Examine the current state of the file in the Node.js repo at mentioned line numbers. (3) Check recent upstream changes by running 'cd ../third_party/electron_node && git log --oneline -10 -- {file}' to see what has been happening in the file. (4) Find the introducing commit and its Node.js PR by examining the commit message for 'PR-URL: https://github.com/nodejs/node/pull/{PR_NUMBER}'.

Resolve patch conflicts by intent, not mechanical merge

When resolving a patch conflict, do not blindly preserve the patch's old code. Instead: (1) Understand the upstream commit's full scope by running 'git show <commit> --stat' and reading diffs for all affected files—upstream may have removed structs, members, or methods that the patch references. (2) Re-read the patch commit message to understand its intent and what behavior it needs to preserve or add. (3) Implement the intent against the new upstream code. For example, if the patch's purpose is to add BoringSSL compatibility, add only the compatibility layer without restoring old code that upstream separately removed.

Upstream removals break patch references

When a patch conflict involves an upstream refactor (not just context drift), check the full diff of the upstream commit for removed types, members, and methods. If the patch's old code references something that upstream removed, the resolution must use the new upstream mechanism rather than restoring the old code.

Separate patch purpose from patch implementation

When a conflict arises between 'upstream simplified code' versus 'patch has older code,' identify the minimal change the patch actually needs. If the patch wraps code in a conditional, only add the conditional without restoring old code that was inside the conditional but was separately cleaned up upstream.

Common patch failure patterns and solutions

Context lines don't match: surrounding code changed—update context in patch. File not found: file renamed or moved—update patch target path. Function not found: refactored upstream—find new function name. OpenSSL to BoringSSL mismatch: crypto API change—update to BoringSSL-compatible API. GYP/GN build change: build system refactor—adapt build patch to new structure. Deleted code: feature removed—verify patch still needed. V8 API bridge patch conflicts: Node.js caught up to Chromium's V8—patch may be deletable if the API is now in Node.js' V8 natively.

How to find the upstream commit for a change

Attribute a fix to the commit that introduced the code it responds to, never to the commit that most recently touched the file. Work against 'refs/patches/upstream-head' (the unpatched Node.js commit) so the answer is an upstream commit and not one of Electron's own patches. Use 'git log -S'{symbol}' refs/patches/upstream-head -- {file}' to find the commit that added or removed a symbol, or 'git blame -L {start},{end} refs/patches/upstream-head -- {file}' to find the commit that last wrote specific lines. Verify the candidate by checking that its diff contains the symbol using 'git show {commit_sha} -- {file} | grep -n '{symbol}'' and look for the PR-URL line in the commit log with 'git log -1 {commit_sha}'.

V8 bridge patches during Node.js upgrades

Electron uses Chromium's V8, which is often ahead of the V8 bundled in Node.js. Many patches exist to bridge this version gap by adapting Node.js code to work with newer V8 APIs that Chromium's V8 exposes. During major Node.js upgrades, Node.js' V8 catches up to Chromium's, and these bridge patches often become unnecessary. Check whether the API the patch shims is now available natively in the new Node.js version's V8.

How to verify patch necessity before deletion

Before deleting a patch, verify: (1) The patched functionality was intentionally removed upstream. (2) Electron doesn't need the patch for other reasons. (3) No other code depends on the patched behavior. When in doubt, keep the patch and adapt it.

Build-time patch issues in Phase Two

Patches that applied successfully in Phase One may cause build errors in Phase Two due to: (1) Incomplete types—a patch disables a header include, but new upstream code uses the type. (2) Missing members—a patch modifies a class, but upstream added new code referencing the original. To find which patch affects a file, run 'grep -l "filename.cc" patches/node/*.patch'.

Match existing patch patterns when fixing build errors

When fixing build errors in patched files, examine the existing patch to understand its style: Does it use '#if 0' / '#endif' guards? Does it use '#if BUILDFLAG(...)' conditionals? Does it use '#ifndef' / '#ifdef' guards for BoringSSL versus OpenSSL? What is the pattern for disabled functionality? Apply fixes consistent with the existing patch style.

Give your agent this brain