Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
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
23 changes: 19 additions & 4 deletions doc/contributing/releases.md
Original file line number Diff line number Diff line change
Expand Up @@ -1379,10 +1379,25 @@ 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, changes that break the native addon ABI and require
a `NODE_MODULE_VERSION` bump, such as V8 updates, may land during the Alpha and
Current phases of a release line. 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. If the change also removes or modifies APIs
that addons use, so that addons need source changes rather than only a
rebuild, the release notes should say so.

Once a release line enters LTS, ABI-breaking changes are strongly discouraged.
They should only land when they are necessary, such as for security fixes, and
when there is no way to make the change without breaking the ABI. Changes that
are not necessary for an LTS line, such as adding fields to a struct to expose
more information in a diagnostic API, do not meet this bar. In practice, this
means V8 is not updated on a release line after it enters LTS.

This policy applies to addons that depend on 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.

### Test releases and release candidates

Expand Down
Loading