Skip to content

Commit c61c722

Browse files
rvaggrvagg
committed
doc: add ABI version registry
PR-URL: #24114 Refs: https://nodejs.org/en/download/releases/ Refs: https://github.com/lgeiger/node-abi/blob/master/index.js Refs: nodejs/TSC#621 Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Ujjwal Sharma <[email protected]> Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: Ali Ijaz Sheikh <[email protected]>
1 parent cdba9f2 commit c61c722

File tree

4 files changed

+84
-45
lines changed

4 files changed

+84
-45
lines changed

‎BUILDING.md

+11-8
Original file line numberDiff line numberDiff line change
@@ -581,11 +581,14 @@ To make `./myModule.js` available via `require('myModule')` and
581581

582582
## Note for downstream distributors of Node.js
583583

584-
The Node.js ecosystem is reliant on ABI compatibility within a major
585-
release. To maintain ABI compatibility it is required that production
586-
builds of Node.js will be built against the same version of dependencies as the
587-
project vendors. If Node.js is to be built against a different version of a
588-
dependency please create a custom `NODE_MODULE_VERSION` to ensure ecosystem
589-
compatibility. Please consult with the TSC by opening an issue at
590-
https://github.com/nodejs/tsc/issues if you decide to create a custom
591-
`NODE_MODULE_VERSION` so we can avoid duplication in the ecosystem.
584+
The Node.js ecosystem is reliant on ABI compatibility within a major release.
585+
To maintain ABI compatibility it is required that distributed builds of Node.js
586+
be built against the same version of dependencies, or similar versions that do
587+
not break their ABI compatibility, as those released by Node.js for any given
588+
`NODE_MODULE_VERSION` (located in `src/node_version.h`).
589+
590+
When Node.js is built (with an intention to distribute) with an ABI
591+
incompatible with the official Node.js builds (e.g. using a ABI incompatible
592+
version of a dependency), please reserve and use a custom `NODE_MODULE_VERSION`
593+
by opening a pull request against the registry available at
594+
<https://github.com/nodejs/node/blob/master/doc/abi_version_registry.json>.

‎doc/abi_version_registry.json

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
{
2+
"NODE_MODULE_VERSION": [
3+
{ "modules": 72, "runtime": "node", "variant": "v8_7.4", "versions": "12.0.0-pre" },
4+
{ "modules": 71, "runtime": "node", "variant": "v8_7.3", "versions": "12.0.0-pre" },
5+
{ "modules": 70, "runtime": "electron", "variant": "electron", "versions": "5" },
6+
{ "modules": 69, "runtime": "electron", "variant": "electron", "versions": "^4.0.5" },
7+
{ "modules": 68, "runtime": "node", "variant": "v8_7.1", "versions": "12.0.0-pre" },
8+
{ "modules": 67, "runtime": "node", "variant": "node", "versions": "11" },
9+
{ "modules": 66, "runtime": "node", "variant": "v8_6.9", "versions": "11.0.0-pre" },
10+
{ "modules": 65, "runtime": "node", "variant": "v8_6.8", "versions": "11.0.0-pre" },
11+
{ "modules": 65, "runtime": "node", "variant": "debian-openssl_1.1.1", "versions": "10" },
12+
{ "modules": 64, "runtime": "node", "variant": "node", "versions": "10" },
13+
{ "modules": 64, "runtime": "electron", "variant": "electron", "versions": ">=3 <4.0.5" },
14+
{ "modules": 63, "runtime": "node", "variant": "v8_6.6", "versions": "10.0.0-pre" },
15+
{ "modules": 62, "runtime": "node", "variant": "v8_6.5", "versions": "10.0.0-pre" },
16+
{ "modules": 61, "runtime": "node", "variant": "v8_6.4", "versions": "10.0.0-pre" },
17+
{ "modules": 60, "runtime": "node", "variant": "v8_6.3", "versions": "10.0.0-pre" },
18+
{ "modules": 59, "runtime": "node", "variant": "node", "versions": "9" },
19+
{ "modules": 59, "runtime": "nw.js", "variant": "nw.js", "versions": "~0.26.5" },
20+
{ "modules": 58, "runtime": "node", "variant": "v8_6.1", "versions": "9.0.0-pre" },
21+
{ "modules": 58, "runtime": "node", "variant": "debian-openssl_1.1.1", "versions": "8" },
22+
{ "modules": 57, "runtime": "node", "variant": "node", "versions": "8" },
23+
{ "modules": 57, "runtime": "electron", "variant": "electron", "versions": ">=1.8 <3" },
24+
{ "modules": 57, "runtime": "nw.js", "variant": "nw.js", "versions": ">=0.23 <0.26.5" },
25+
{ "modules": 56, "runtime": "node", "variant": "v8_5.9", "versions": "8.0.0-pre" },
26+
{ "modules": 55, "runtime": "node", "variant": "v8_5.8", "versions": "8.0.0-pre" },
27+
{ "modules": 54, "runtime": "node", "variant": "v8_5.7", "versions": "8.0.0-pre" },
28+
{ "modules": 54, "runtime": "electron", "variant": "electron", "versions": "1.7" },
29+
{ "modules": 53, "runtime": "node", "variant": "v8_5.6", "versions": "8.0.0-pre" },
30+
{ "modules": 53, "runtime": "electron", "variant": "electron", "versions": "1.6" },
31+
{ "modules": 52, "runtime": "node", "variant": "v8_5.5", "versions": "8.0.0-pre" },
32+
{ "modules": 51, "runtime": "node", "variant": "node", "versions": "7" },
33+
{ "modules": 51, "runtime": "electron", "variant": "electron", "versions": "1.5" },
34+
{ "modules": 51, "runtime": "nw.js", "variant": "nw.js", "versions": ">=0.18.3 <0.24" },
35+
{ "modules": 50, "runtime": "electron", "variant": "electron", "versions": "1.4" },
36+
{ "modules": 49, "runtime": "electron", "variant": "electron", "versions": "1.3" },
37+
{ "modules": 48, "runtime": "node", "variant": "node", "versions": "6" },
38+
{ "modules": 48, "runtime": "electron", "variant": "electron", "versions": ">1.1 <1.3" },
39+
{ "modules": 48, "runtime": "nw.js", "variant": "nw.js", "versions": "6" },
40+
{ "modules": 47, "runtime": "node", "variant": "node", "versions": "5" },
41+
{ "modules": 47, "runtime": "electron", "variant": "electron", "versions": "0.36" },
42+
{ "modules": 47, "runtime": "nw.js", "variant": "nw.js", "versions": "0.13" },
43+
{ "modules": 46, "runtime": "node", "variant": "node", "versions": "4" },
44+
{ "modules": 46, "runtime": "electron", "variant": "electron", "versions": ">=0.33 <0.36" },
45+
{ "modules": 45, "runtime": "node", "variant": "io.js", "versions": "3" },
46+
{ "modules": 45, "runtime": "electron", "variant": "electron", "versions": ">=0.31 <0.33" },
47+
{ "modules": 44, "runtime": "node", "variant": "io.js", "versions": "2" },
48+
{ "modules": 44, "runtime": "electron", "variant": "electron", "versions": "0.30" },
49+
{ "modules": 43, "runtime": "node", "variant": "io.js", "versions": ">=1.1 <2" },
50+
{ "modules": 42, "runtime": "node", "variant": "io.js", "versions": "1.0" },
51+
{ "modules": 14, "runtime": "node", "variant": "node", "versions": ">=0.11.11 <0.13" },
52+
{ "modules": 13, "runtime": "node", "variant": "node", "versions": ">=0.11.8 <0.11.11" },
53+
{ "modules": 12, "runtime": "node", "variant": "node", "versions": ">=0.11.0 <0.11.8" },
54+
{ "modules": 11, "runtime": "node", "variant": "node", "versions": ">=0.9.9 <0.11" },
55+
{ "modules": 10, "runtime": "node", "variant": "node", "versions": ">=0.9.1 <0.9.9" },
56+
{ "modules": 1, "runtime": "node", "variant": "node", "versions": ">=0.2.0 <0.9.8" }
57+
]
58+
}

‎doc/releases.md

+6
Original file line numberDiff line numberDiff line change
@@ -235,6 +235,12 @@ and also if there are non-trivial API changes. The rules are not yet strictly
235235
defined, so if in doubt, please confer with someone that will have a more
236236
informed perspective, such as a member of the NAN team.
237237

238+
A registry of currently used `NODE_MODULE_VERSION` values is maintained at
239+
<https://github.com/nodejs/node/blob/master/doc/abi_version_registry.json>.
240+
When bumping `NODE_MODULE_VERSION`, you should choose a new value not listed
241+
in the registry. Also include a change to the registry in your commit to
242+
reflect the newly used value.
243+
238244
It is current TSC policy to bump major version when ABI changes. If you
239245
see a need to bump `NODE_MODULE_VERSION` then you should consult the TSC.
240246
Commits may need to be reverted or a major version bump may need to happen.

‎src/node_version.h

+9-37
Original file line numberDiff line numberDiff line change
@@ -75,47 +75,19 @@
7575
* Node.js will refuse to load modules that weren't compiled against its own
7676
* module ABI number, exposed as the process.versions.modules property.
7777
*
78-
* When this version number is changed, node.js will refuse
79-
* to load older modules. This should be done whenever
80-
* an API is broken in the C++ side, including in v8 or
81-
* other dependencies.
78+
* Node.js will refuse to load modules with a non-matching ABI version. The
79+
* version number here should be changed whenever an ABI-incompatible API change
80+
* is made in the C++ side, including in V8 or other dependencies.
8281
*
8382
* Node.js will not change the module version during a Major release line
84-
* We will at times update the version of V8 shipped in the release line
83+
* We will, at times update the version of V8 shipped in the release line
8584
* if it can be made ABI compatible with the previous version.
8685
*
87-
* Module version by Node.js version:
88-
* Node.js v0.10.x: 11
89-
* Node.js v0.12.x: 14
90-
* Node.js v4.x: 46
91-
* Node.js v5.x: 47
92-
* Node.js v6.x: 48
93-
* Node.js v7.x: 51
94-
* Node.js v8.x: 57
95-
*
96-
* Module version by V8 ABI version:
97-
* V8 5.4: 51
98-
* V8 5.5: 52
99-
* V8 5.6: 53
100-
* V8 5.7: 54
101-
* V8 5.8: 55
102-
* V8 5.9: 56
103-
* V8 6.0: 57
104-
* V8 6.1: 58
105-
* V8 6.2: 59
106-
* V8 6.3: 60
107-
* V8 6.4: 61
108-
* V8 6.5: 62
109-
* V8 6.6: 63
110-
* V8 6.7: 64
111-
* V8 6.8: 65
112-
* V8 6.9: 66
113-
* V8 7.0: 67
114-
* V8 7.1: 68
115-
* V8 7.3: 71
116-
* V8 7.4: 72
117-
*
118-
* More information can be found at https://nodejs.org/en/download/releases/
86+
* The registry of used NODE_MODULE_VERSION numbers is located at
87+
* https://github.com/nodejs/node/blob/master/doc/abi_version_registry.json
88+
* Extenders, embedders and other consumers of Node.js that require ABI
89+
* version matching should open a pull request to reserve a number in this
90+
* registry.
11991
*/
12092
#define NODE_MODULE_VERSION 72
12193

0 commit comments

Comments
 (0)