Skip to content

doc: add doc on when to backport V8 patches to main #66710

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
legendecas wants to merge 4 commits into
base: main
Choose a base branch
from
+20 −0
Open

doc: add doc on when to backport V8 patches to main #66710

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6c5b94b
doc: add doc on when to backport V8 patches to main
legendecas Oct 13, 2026
2965bfa
fixup! doc: add doc on when to backport V8 patches to main
legendecas Oct 13, 2026
84fd457
fixup! doc: add doc on when to backport V8 patches to main
legendecas Oct 13, 2026
45007af
fixup! doc: add doc on when to backport V8 patches to main
legendecas Oct 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions doc/contributing/maintaining/maintaining-V8.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,26 @@ fixed upstream first.
branches that are still active or are branches that Node.js cares about.
Follow the process for backporting below.

### Backporting patches to `main`

As a general rule, do not backport individual V8 patches to the Node.js `main`
branch. Wait for them to be included in a V8 major version update instead.
An individual V8 patch adds up audit cost and further delays the pending V8
update.

A patch may be backported to `main` when at least one of these criteria applies:

* It fixes a build issue on a platform or toolchain supported on `main`.
* It fixes a security issue.
* It unblocks a pending V8 update, for example by adjusting how the Node.js code
uses a V8 API.
Comment on lines +91 to +92

@joyeecheung joyeecheung Oct 14, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* It unblocks a pending V8 update, for example by adjusting how the Node.js code
uses a V8 API.
* It unblocks a pending V8 update, for example by adjusting how the Node.js code
uses a V8 API.

Isn't it the reverse i.e. I think this is talking about the situation where we change src/ or some gyp files, not deps/v8/ but in anticipation of deps/v8 changes, even though this section is supposed to be about changes to deps/v8? If we are trying to cover cases where we are updating deps/v8/ so that we can land some change in src/, I think it generally goes to the second category.

@legendecas legendecas Oct 14, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking of cases in the past like V8 global proxy interceptor and vm changes, where we have to update both node_contextify, and apply the V8 changes together to avoid breaking behavior in the upcoming V8 upgrade. I limited this to "unblocks a pending V8 update" so that it does not encourage new language features to be individually backported.


If the patch meet the following criteria, it's recommended to backport the patches
to the release staging branches like `v<MAJOR>.x-staging`, instead of `main`:

@aduh95 aduh95 Oct 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need to also remind folks that we typically don't accept PRs targeting LTS staging branches?

@legendecas legendecas Oct 14, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would you like suggest words? I didn't find any docs saying the criteria on backporting dependency patches specifically.


* It has demonstrated real-world urgency and impact that justifies landing it
before the next V8 major version update.

### Backporting to active branches

If the bug exists in any of the active V8 branches, we may need to get the fix
Expand Down
Loading