Skip to content

Commit 2b05131

Browse files
committed
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: nodejs/TSC#1852 (comment) Signed-off-by: RafaelGSS <[email protected]>
1 parent 9ad22d1 commit 2b05131

2 files changed

Lines changed: 18 additions & 4 deletions

File tree

‎doc/contributing/maintaining/maintaining-V8.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -308,6 +308,10 @@ Revision_ from the 5.4 branch that can be useful in the update process above.
308308
We upgrade the version of V8 in Node.js `main` whenever a V8 release goes stable
309309
upstream, that is, whenever a new release of Chrome comes out.
310310

311+
V8 updates can require a `NODE_MODULE_VERSION` bump if they change the native
312+
addon ABI. See the release process documentation for when
313+
`NODE_MODULE_VERSION` may be updated during a release line.
314+
311315
Upgrading major versions would be much harder to do with the patch mechanism
312316
above. A better strategy is to
313317

‎doc/contributing/releases.md‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1379,10 +1379,20 @@ in the registry. Also include a change to the registry in your commit to
13791379
reflect the newly used value. Ensure that the release commit removes the
13801380
`-pre` suffix for the major version being prepared.
13811381

1382-
It is current TSC policy to bump major version when ABI changes. If you
1383-
see a need to bump `NODE_MODULE_VERSION` outside of a major release then
1384-
you should consult the TSC. Commits may need to be reverted or a major
1385-
version bump may need to happen.
1382+
Starting with Node.js 27, V8 updates may land during the Alpha and Current
1383+
phases of a release line even if they require a `NODE_MODULE_VERSION` bump.
1384+
Such changes should still be labeled as semver-major on the default branch.
1385+
When they are promoted to the release line, they may land in semver-minor
1386+
releases as long as the ABI change is clearly documented in the release notes.
1387+
1388+
The native addon ABI is frozen when a release line enters LTS. After LTS
1389+
promotion, V8 updates that require a `NODE_MODULE_VERSION` bump are only
1390+
permitted in exceptional cases such as security fixes. They are not permitted
1391+
in Maintenance releases.
1392+
1393+
This policy applies to addons that depend on the V8, Node.js, or other
1394+
non-Node-API native interfaces. Node-API remains the recommended interface for
1395+
native addons that require ABI stability across Node.js versions.
13861396

13871397
### Test releases and release candidates
13881398

0 commit comments

Comments
 (0)