From 2b05131680a160b9c404b135db4b6e9246a121f2 Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Mon, 29 Jun 2026 10:47:27 -0300 Subject: [PATCH 1/2] doc: update V8 ABI release policy Document the V8-related native addon ABI policy discussed in nodejs/TSC#1852. Starting with Node.js 27, V8 updates may land during Alpha and Current even when they require a `NODE_MODULE_VERSION` bump, as long as the ABI change is documented in release notes. Refs: https://github.com/nodejs/TSC/issues/1852#issuecomment-4566968175 Signed-off-by: RafaelGSS --- doc/contributing/maintaining/maintaining-V8.md | 4 ++++ doc/contributing/releases.md | 18 ++++++++++++++---- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/doc/contributing/maintaining/maintaining-V8.md b/doc/contributing/maintaining/maintaining-V8.md index 740af7f228f6..63daa086fe25 100644 --- a/doc/contributing/maintaining/maintaining-V8.md +++ b/doc/contributing/maintaining/maintaining-V8.md @@ -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 diff --git a/doc/contributing/releases.md b/doc/contributing/releases.md index 1f33d8f27717..d57092a4b5ad 100644 --- a/doc/contributing/releases.md +++ b/doc/contributing/releases.md @@ -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. + +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. ### Test releases and release candidates From d59f6b00d0a5653f55aa256345339fab2be21979 Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Thu, 1 Oct 2026 15:38:15 +0200 Subject: [PATCH 2/2] fixup! doc: update V8 ABI release policy Signed-off-by: RafaelGSS --- doc/contributing/releases.md | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/doc/contributing/releases.md b/doc/contributing/releases.md index d57092a4b5ad..3dca4e8b57ef 100644 --- a/doc/contributing/releases.md +++ b/doc/contributing/releases.md @@ -1379,20 +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. -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. - -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. +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