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..3dca4e8b57ef 100644 --- a/doc/contributing/releases.md +++ b/doc/contributing/releases.md @@ -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