Skip to content

Commit 8df2dd8

Browse files
authored
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 <rafael.nunu@hotmail.com> PR-URL: #64196 Refs: nodejs/TSC#1852 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Robert Nagy <ronagy@icloud.com> Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> Reviewed-By: Richard Lau <richard.lau@ibm.com>
1 parent 8175dc3 commit 8df2dd8

2 files changed

Lines changed: 24 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
@@ -330,6 +330,10 @@ Revision_ from the 5.4 branch that can be useful in the update process above.
330330
We upgrade the version of V8 in Node.js `main` whenever a V8 release goes stable
331331
upstream, that is, whenever a new release of Chrome comes out.
332332

333+
V8 updates can require a `NODE_MODULE_VERSION` bump if they change the native
334+
addon ABI. See the release process documentation for when
335+
`NODE_MODULE_VERSION` may be updated during a release line.
336+
333337
Upgrading major versions would be much harder to do with the patch mechanism
334338
above. A better strategy is to
335339

‎doc/contributing/releases.md‎

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

1463-
It is current TSC policy to bump major version when ABI changes. If you
1464-
see a need to bump `NODE_MODULE_VERSION` outside of a major release then
1465-
you should consult the TSC. Commits may need to be reverted or a major
1466-
version bump may need to happen.
1463+
Starting with Node.js 27, changes that break the native addon ABI and require
1464+
a `NODE_MODULE_VERSION` bump, such as V8 updates, may land during the Alpha and
1465+
Current phases of a release line. Such changes should still be labeled as
1466+
semver-major on the default branch. When they are promoted to the release line,
1467+
they may land in semver-minor releases as long as the ABI change is clearly
1468+
documented in the release notes.
1469+
1470+
Once a release line enters LTS, ABI-breaking changes are strongly discouraged.
1471+
They should only land when they are necessary, such as for security fixes, and
1472+
when there is no way to make the change without breaking the ABI. Breaking
1473+
changes that are not necessary for an LTS line, such as adding fields to a
1474+
struct to expose more information in a diagnostic API, do not meet this bar,
1475+
and should be reworked as non-breaking changes before they could land. In
1476+
practice, this means V8 is generally stable on a release line after it enters
1477+
LTS, and no ABI or API breaking changes
1478+
are expected unless in exceptional circumstances.
1479+
1480+
This policy applies to addons that depend on V8, Node.js, or other non-Node-API
1481+
native interfaces. Node-API remains the recommended interface for native addons
1482+
that require ABI stability across Node.js versions.
14671483

14681484
##### Changelogs
14691485

0 commit comments

Comments
 (0)