out of scope

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

Patch conflict fix commit format

Patch conflict fixes use the fix(patch): prefix. The title names the upstream change, not your response to it. Use the upstream commit's subject line verbatim after the prefix, do not paraphrase it, and do not invent a headline from the file's recent history. Format: fix(patch): {topic headline}\n\nRef: {Node.js commit or issue link}\n\nCo-Authored-By: <AI model attribution>. Only add a description body if it provides clarity beyond the title.

Phase One commit guidelines overview

Phase One commit guidelines apply only when there are uncommitted changes to patches/ after Phase One succeeds. These guidelines are critically important and must be followed instead of other commit message conventions.

Each patch conflict resolution must be complete

When resolving a patch conflict, fully adapt the patch to the new upstream code in the same commit. If the upstream change removes an API the patch uses, update the patch to use the replacement API immediately rather than deferring it to a future phase. Each commit should represent a finished resolution, not a partial one.

Commit title character limits

Commit titles follow a 60/80-character guideline: simple changes fit within 60 characters, otherwise the limit is 80 characters.

Upstreamed patch removal commit format

When patches are no longer needed (applied cleanly or confirmed upstreamed), group ALL removals into a single commit. Use chore: remove upstreamed patch (singular) or chore: remove upstreamed patches (plural). If the patch originated from an upstream Node.js PR, no extra Ref: is needed. Otherwise, add a Ref: pointing to the relevant Node.js issue or commit if one exists.

Trivial patch updates commit format

After all fix commits, stage remaining trivial changes (index, line numbers, context only) with the commit message: chore: update patches (trivial only). A git am conflict does not always mean the patch content changed — context drift alone can cause a conflict. If only index hashes, line numbers, and context lines changed (not the patch's own +/- lines), it is trivial and belongs here, not in a fix(patch): commit.

Atomic commits per patch conflict fix

Each patch conflict fix gets its own commit with its own Ref. Try hard to find the PR or commit reference. Each change should in theory have been in response to a change made in Node.js that you identified or can identify.

Reuse fixes from sibling roller branches

The same Node.js version is usually rolled to main and to every supported release branch at about the same time, and the fixes are nearly always identical. Before writing a fix, check whether it already exists in sibling roller/node/main and roller/node/{N}-x-y branches. If a matching fix exists, reuse it: same patch file name, same patch content, same commit title and Ref. Cherry-pick the commit when it applies cleanly. Diverge only when the code on your branch genuinely differs, and say so in the commit body. Two branches carrying the same fix under different file names or different attributions is a review blocker.

Finding upstream commit references for patch fixes

The Ref: must point at the upstream commit that introduced the code your fix responds to, not at whichever commit most recently touched the file. Required procedure in ../third_party/electron_node: (1) Name the exact symbol or lines your fix touches; (2) Find the commit that introduced them using git log -S'{symbol}' refs/patches/upstream-head -- {file} or git blame -L {start},{end} refs/patches/upstream-head -- {file}; (3) Verify the candidate by checking its diff contains the symbol; (4) Take the reference from that commit's trailers, specifically PR-URL: https://github.com/nodejs/node/pull/XXXXX. If no reference found after searching, use: Ref: Unable to locate reference.

Upstream commit identification is more important than recent commits

Recency queries such as git log -10 -- {file} are for orientation only; several later commits often touch the same file, and the newest one is usually the wrong answer. The introducing commit is the correct one to reference.

Example patch conflict fix commit

Example simple patch conflict fix: fix(patch): stop using v8::PropertyCallbackInfo<T>::This() Ref: https://github.com/nodejs/node/issues/60616 Co-Authored-By: <AI model attribution>

Example patch conflict fix with complex description

Example patch conflict fix with description: fix(patch): BoringSSL and OpenSSL incompatibilities Upstream updated OpenSSL APIs that diverge from BoringSSL. Adapted the compatibility shims in crypto patches to use the BoringSSL equivalents. Ref: Unable to locate reference Co-Authored-By: <AI model attribution>

Example Phase Two commit with upstream PR

Example commit message for Electron source fix with upstream PR: node#61898: src: stop using v8::PropertyCallbackInfo<T>::This() followed by Ref: https://github.com/nodejs/node/pull/61898 and Co-Authored-By: <AI model attribution>

Example Phase Two commit with issue reference

Example commit message for Electron source fix with issue reference: fix: adapt to v8::PropertyCallbackInfo<T>::This() removal, followed by body text explaining the change: Updated NodeBindings to use HolderV2() after upstream Node.js stopped using the deprecated This() API. Then Ref: https://github.com/nodejs/node/issues/60616 and Co-Authored-By: <AI model attribution>

Electron source changes commit format with upstream PR

For Electron source changes (shell/, electron/, etc.) when the upstream Node.js commit has a PR-URL, use this format: node#{PR-Number}: {upstream PR's original title}, followed by Ref: {Node.js PR link} and Co-Authored-By: <AI model attribution>. Use the upstream commit's original title verbatim without paraphrasing.

Electron source changes commit format without PR-URL

For Electron source changes when there is no PR-URL but there is an issue reference or commit, use this format: fix: {description of the adaptation}, followed by Ref: {Node.js issue or commit link} and Co-Authored-By: <AI model attribution>.

When to include body text in Phase Two commits

Only add a description body to Phase Two commits if it provides clarity beyond what the title already says, such as when Electron's adaptation is non-obvious. For simple renames, method additions, or straightforward API updates, the title plus Ref link is sufficient.

Phase Two commit message title length guidelines

Commit titles follow the 60/80-character guideline: simple changes fit within 60 characters, otherwise the limit is 80 characters. Exception: upstream Node.js PR titles are used verbatim even if longer.

Co-Authored-By trailer requirement for Phase Two commits

All commit messages must include a Co-Authored-By trailer identifying the AI model that assisted, for example: Co-Authored-By: <AI model attribution>.

Logical grouping of changes in Phase Two commits

Each change should have its own commit and its own Ref. Logically group changes into commits that make sense rather than one giant commit. Multiple Ref links may be included if required.

Finding upstream Node.js references for Phase Two commits

Try hard to find a reference for each change. Each change should theoretically correspond to a change in Node.js. Check git log and git blame in the Node.js repo. The most recent commit to touch the file is not necessarily the answer; verify that the commit's diff contains the symbol before taking its PR-URL and subject line. Use git log -S or git blame against refs/patches/upstream-head to identify the commit that introduced the symbol.

Checking sibling roller branches for existing fixes

Before writing any fix in Phase Two, check roller/node/main and sibling roller/node/{N}-x-y branches for the same version. Build breaks from a Node.js bump are the same on every branch, and the fix should be reused.

Patch file updates commit format for Phase Two

For patch updates (patches/node/*.patch), use the same fixup workflow as Phase One and follow phase-one-commit-guidelines.md for the commit message format with fix(patch): prefix and topic style.

Dependent patch header updates after modifications

After any patch modification, check for other affected patches using git status. If other .patch files show as modified with only index, line number, and context changes, add all patches with git add patches/ and commit with message: chore: update patches (trivial only).

Reference not found fallback for Phase Two commits

If no reference is found after searching, use: Ref: Unable to locate reference

Give your agent this brain