doc: update V8 ABI release policy#64196
Conversation
|
Review requested:
|
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>
RafaelGSS
force-pushed
the
drop-abi-stability-v27
branch
from
7f68146 to
2b05131
Compare
| 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. |
There was a problem hiding this comment.
Why is this limited to V8? What does it mean for ABI stability for Node.js-specific native APIs?
Also I'm not sure we have consensus for freezing ABI when entering LTS, IIRC there was interest in backporting ABI-breaking changes to LTS as well
There was a problem hiding this comment.
I think freezing may not be necessary, but it's good to discourage ABI breaking changes once in LTS unless it's absolutely necessary (security fixes, mostly) and and inevitable (that is, there's no way to patch it to make it non-breaking - it's usually more possible than what people think). That also means no V8 upgrades after LTS, which I think isn't going to be a huge problem as at that point we should be busy upgrading another new release line instead of trying to upgrade a very old line that's >1 yo after it's cut. But it's useful to set a higher bar for LTS in case otherwise people start requesting to backport "this ABI breaking change that adds a field into a struct so that we can use it in a diagnostic API to surface more information" (there had been several of those) which isn't really necessary for LTS (it's just a feature we can live without) nor inevitable (you may be able to avoid the breakage by e.g. adding a new API that use a duplicate-with-one-more-field struct on a specific branch, for example), the bar would force people to think twice and try harder.
| permitted in exceptional cases such as security fixes. They are not permitted | ||
| in Maintenance releases. |
There was a problem hiding this comment.
As of Node.js 27, we no longer have a Maintenance status
6 participants
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_VERSIONbump, as long as the ABI change is documented in release notes.Refs: nodejs/TSC#1852 (comment)
@nodejs/tsc @nodejs/releasers