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>
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.
There was a problem hiding this comment.
Thanks the explainer, that sounds good to me. Still, we should probably update the wording to remove the mention of V8 updates to instead talk about ABI-breaking changes in general (or rather only mention V8 as an example instead of the subject of the sentence)
| 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
| 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 |
There was a problem hiding this comment.
Not sure if this is the right PR to ask but what about API changes in such new V8 versions landing in Current?
e.g. v8 removes/deprecates an API in the new version.
If only ABI changes a recompile of an addon should be enough, for API changes code might need adaptions.
7 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