Skip to content

doc: update V8 ABI release policy #64196

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
RafaelGSS wants to merge 1 commit into
base: main
Choose a base branch
from
+18 −4
Open

doc: update V8 ABI release policy #64196

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 4 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 @@ -308,6 +308,10 @@ Revision_ from the 5.4 branch that can be useful in the update process above.
We upgrade the version of V8 in Node.js `main` whenever a V8 release goes stable
upstream, that is, whenever a new release of Chrome comes out.

V8 updates can require a `NODE_MODULE_VERSION` bump if they change the native
addon ABI. See the release process documentation for when
`NODE_MODULE_VERSION` may be updated during a release line.

Upgrading major versions would be much harder to do with the patch mechanism
above. A better strategy is to

Expand Down
18 changes: 14 additions & 4 deletions doc/contributing/releases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1379,10 +1379,20 @@ in the registry. Also include a change to the registry in your commit to
reflect the newly used value. Ensure that the release commit removes the
`-pre` suffix for the major version being prepared.

It is current TSC policy to bump major version when ABI changes. If you
see a need to bump `NODE_MODULE_VERSION` outside of a major release then
you should consult the TSC. Commits may need to be reverted or a major
version bump may need to happen.
Starting with Node.js 27, V8 updates may land during the Alpha and Current
phases of a release line even if they require a `NODE_MODULE_VERSION` bump.
Such changes should still be labeled as semver-major on the default branch.
When they are promoted to the release line, they may land in semver-minor
releases as long as the ABI change is clearly documented in the release notes.

The native addon ABI is frozen when a release line enters LTS. After LTS
promotion, V8 updates that require a `NODE_MODULE_VERSION` bump are only
permitted in exceptional cases such as security fixes. They are not permitted
in Maintenance releases.
Comment on lines +1390 to +1391

@aduh95 aduh95 Jun 30, 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.

As of Node.js 27, we no longer have a Maintenance status


This policy applies to addons that depend on the V8, Node.js, or other
non-Node-API native interfaces. Node-API remains the recommended interface for
native addons that require ABI stability across Node.js versions.
Comment on lines +1382 to +1395

@aduh95 aduh95 Jun 30, 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.

Why is this limited to V8? What does it mean for ABI stability for Node.js-specific native APIs?

Also I'm not sure we have consensus for freezing ABI when entering LTS, IIRC there was interest in backporting ABI-breaking changes to LTS as well

@joyeecheung joyeecheung Jul 1, 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.

I think freezing may not be necessary, but it's good to discourage ABI breaking changes once in LTS unless it's absolutely necessary (security fixes, mostly) and and inevitable (that is, there's no way to patch it to make it non-breaking - it's usually more possible than what people think). That also means no V8 upgrades after LTS, which I think isn't going to be a huge problem as at that point we should be busy upgrading another new release line instead of trying to upgrade a very old line that's >1 yo after it's cut. But it's useful to set a higher bar for LTS in case otherwise people start requesting to backport "this ABI breaking change that adds a field into a struct so that we can use it in a diagnostic API to surface more information" (there had been several of those) which isn't really necessary for LTS (it's just a feature we can live without) nor inevitable (you may be able to avoid the breakage by e.g. adding a new API that use a duplicate-with-one-more-field struct on a specific branch, for example), the bar would force people to think twice and try harder.


### Test releases and release candidates

Expand Down
Loading