diff --git a/BUILDING.md b/BUILDING.md index c363279ee5e70d..61587317b7f8ab 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -581,11 +581,14 @@ To make `./myModule.js` available via `require('myModule')` and ## Note for downstream distributors of Node.js -The Node.js ecosystem is reliant on ABI compatibility within a major -release. To maintain ABI compatibility it is required that production -builds of Node.js will be built against the same version of dependencies as the -project vendors. If Node.js is to be built against a different version of a -dependency please create a custom `NODE_MODULE_VERSION` to ensure ecosystem -compatibility. Please consult with the TSC by opening an issue at -https://github.com/nodejs/tsc/issues if you decide to create a custom -`NODE_MODULE_VERSION` so we can avoid duplication in the ecosystem. +The Node.js ecosystem is reliant on ABI compatibility within a major release. +To maintain ABI compatibility it is required that distributed builds of Node.js +be built against the same version of dependencies, or similar versions that do +not break their ABI compatibility, as those released by Node.js for any given +`NODE_MODULE_VERSION` (located in `src/node_version.h`). + +When Node.js is built (with an intention to distribute) with an ABI +incompatible with the official Node.js builds (e.g. using a ABI incompatible +version of a dependency), please reserve and use a custom `NODE_MODULE_VERSION` +by opening a pull request against the registry available at +. diff --git a/doc/abi_version_registry.json b/doc/abi_version_registry.json new file mode 100644 index 00000000000000..06a976d9affed5 --- /dev/null +++ b/doc/abi_version_registry.json @@ -0,0 +1,58 @@ +{ + "NODE_MODULE_VERSION": [ + { "modules": 72, "runtime": "node", "variant": "v8_7.4", "versions": "12.0.0-pre" }, + { "modules": 71, "runtime": "node", "variant": "v8_7.3", "versions": "12.0.0-pre" }, + { "modules": 70, "runtime": "electron", "variant": "electron", "versions": "5" }, + { "modules": 69, "runtime": "electron", "variant": "electron", "versions": "^4.0.5" }, + { "modules": 68, "runtime": "node", "variant": "v8_7.1", "versions": "12.0.0-pre" }, + { "modules": 67, "runtime": "node", "variant": "node", "versions": "11" }, + { "modules": 66, "runtime": "node", "variant": "v8_6.9", "versions": "11.0.0-pre" }, + { "modules": 65, "runtime": "node", "variant": "v8_6.8", "versions": "11.0.0-pre" }, + { "modules": 65, "runtime": "node", "variant": "debian-openssl_1.1.1", "versions": "10" }, + { "modules": 64, "runtime": "node", "variant": "node", "versions": "10" }, + { "modules": 64, "runtime": "electron", "variant": "electron", "versions": ">=3 <4.0.5" }, + { "modules": 63, "runtime": "node", "variant": "v8_6.6", "versions": "10.0.0-pre" }, + { "modules": 62, "runtime": "node", "variant": "v8_6.5", "versions": "10.0.0-pre" }, + { "modules": 61, "runtime": "node", "variant": "v8_6.4", "versions": "10.0.0-pre" }, + { "modules": 60, "runtime": "node", "variant": "v8_6.3", "versions": "10.0.0-pre" }, + { "modules": 59, "runtime": "node", "variant": "node", "versions": "9" }, + { "modules": 59, "runtime": "nw.js", "variant": "nw.js", "versions": "~0.26.5" }, + { "modules": 58, "runtime": "node", "variant": "v8_6.1", "versions": "9.0.0-pre" }, + { "modules": 58, "runtime": "node", "variant": "debian-openssl_1.1.1", "versions": "8" }, + { "modules": 57, "runtime": "node", "variant": "node", "versions": "8" }, + { "modules": 57, "runtime": "electron", "variant": "electron", "versions": ">=1.8 <3" }, + { "modules": 57, "runtime": "nw.js", "variant": "nw.js", "versions": ">=0.23 <0.26.5" }, + { "modules": 56, "runtime": "node", "variant": "v8_5.9", "versions": "8.0.0-pre" }, + { "modules": 55, "runtime": "node", "variant": "v8_5.8", "versions": "8.0.0-pre" }, + { "modules": 54, "runtime": "node", "variant": "v8_5.7", "versions": "8.0.0-pre" }, + { "modules": 54, "runtime": "electron", "variant": "electron", "versions": "1.7" }, + { "modules": 53, "runtime": "node", "variant": "v8_5.6", "versions": "8.0.0-pre" }, + { "modules": 53, "runtime": "electron", "variant": "electron", "versions": "1.6" }, + { "modules": 52, "runtime": "node", "variant": "v8_5.5", "versions": "8.0.0-pre" }, + { "modules": 51, "runtime": "node", "variant": "node", "versions": "7" }, + { "modules": 51, "runtime": "electron", "variant": "electron", "versions": "1.5" }, + { "modules": 51, "runtime": "nw.js", "variant": "nw.js", "versions": ">=0.18.3 <0.24" }, + { "modules": 50, "runtime": "electron", "variant": "electron", "versions": "1.4" }, + { "modules": 49, "runtime": "electron", "variant": "electron", "versions": "1.3" }, + { "modules": 48, "runtime": "node", "variant": "node", "versions": "6" }, + { "modules": 48, "runtime": "electron", "variant": "electron", "versions": ">1.1 <1.3" }, + { "modules": 48, "runtime": "nw.js", "variant": "nw.js", "versions": "6" }, + { "modules": 47, "runtime": "node", "variant": "node", "versions": "5" }, + { "modules": 47, "runtime": "electron", "variant": "electron", "versions": "0.36" }, + { "modules": 47, "runtime": "nw.js", "variant": "nw.js", "versions": "0.13" }, + { "modules": 46, "runtime": "node", "variant": "node", "versions": "4" }, + { "modules": 46, "runtime": "electron", "variant": "electron", "versions": ">=0.33 <0.36" }, + { "modules": 45, "runtime": "node", "variant": "io.js", "versions": "3" }, + { "modules": 45, "runtime": "electron", "variant": "electron", "versions": ">=0.31 <0.33" }, + { "modules": 44, "runtime": "node", "variant": "io.js", "versions": "2" }, + { "modules": 44, "runtime": "electron", "variant": "electron", "versions": "0.30" }, + { "modules": 43, "runtime": "node", "variant": "io.js", "versions": ">=1.1 <2" }, + { "modules": 42, "runtime": "node", "variant": "io.js", "versions": "1.0" }, + { "modules": 14, "runtime": "node", "variant": "node", "versions": ">=0.11.11 <0.13" }, + { "modules": 13, "runtime": "node", "variant": "node", "versions": ">=0.11.8 <0.11.11" }, + { "modules": 12, "runtime": "node", "variant": "node", "versions": ">=0.11.0 <0.11.8" }, + { "modules": 11, "runtime": "node", "variant": "node", "versions": ">=0.9.9 <0.11" }, + { "modules": 10, "runtime": "node", "variant": "node", "versions": ">=0.9.1 <0.9.9" }, + { "modules": 1, "runtime": "node", "variant": "node", "versions": ">=0.2.0 <0.9.8" } + ] +} diff --git a/doc/releases.md b/doc/releases.md index b03c623ecfd45c..483b1f030c4071 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -235,6 +235,12 @@ and also if there are non-trivial API changes. The rules are not yet strictly defined, so if in doubt, please confer with someone that will have a more informed perspective, such as a member of the NAN team. +A registry of currently used `NODE_MODULE_VERSION` values is maintained at +. +When bumping `NODE_MODULE_VERSION`, you should choose a new value not listed +in the registry. Also include a change to the registry in your commit to +reflect the newly used value. + It is current TSC policy to bump major version when ABI changes. If you see a need to bump `NODE_MODULE_VERSION` then you should consult the TSC. Commits may need to be reverted or a major version bump may need to happen. diff --git a/src/node_version.h b/src/node_version.h index 349d73d18de93b..742ea6e62ecc73 100644 --- a/src/node_version.h +++ b/src/node_version.h @@ -75,47 +75,19 @@ * Node.js will refuse to load modules that weren't compiled against its own * module ABI number, exposed as the process.versions.modules property. * - * When this version number is changed, node.js will refuse - * to load older modules. This should be done whenever - * an API is broken in the C++ side, including in v8 or - * other dependencies. + * Node.js will refuse to load modules with a non-matching ABI version. The + * version number here should be changed whenever an ABI-incompatible API change + * is made in the C++ side, including in V8 or other dependencies. * * Node.js will not change the module version during a Major release line - * We will at times update the version of V8 shipped in the release line + * We will, at times update the version of V8 shipped in the release line * if it can be made ABI compatible with the previous version. * - * Module version by Node.js version: - * Node.js v0.10.x: 11 - * Node.js v0.12.x: 14 - * Node.js v4.x: 46 - * Node.js v5.x: 47 - * Node.js v6.x: 48 - * Node.js v7.x: 51 - * Node.js v8.x: 57 - * - * Module version by V8 ABI version: - * V8 5.4: 51 - * V8 5.5: 52 - * V8 5.6: 53 - * V8 5.7: 54 - * V8 5.8: 55 - * V8 5.9: 56 - * V8 6.0: 57 - * V8 6.1: 58 - * V8 6.2: 59 - * V8 6.3: 60 - * V8 6.4: 61 - * V8 6.5: 62 - * V8 6.6: 63 - * V8 6.7: 64 - * V8 6.8: 65 - * V8 6.9: 66 - * V8 7.0: 67 - * V8 7.1: 68 - * V8 7.3: 71 - * V8 7.4: 72 - * - * More information can be found at https://nodejs.org/en/download/releases/ + * The registry of used NODE_MODULE_VERSION numbers is located at + * https://github.com/nodejs/node/blob/master/doc/abi_version_registry.json + * Extenders, embedders and other consumers of Node.js that require ABI + * version matching should open a pull request to reserve a number in this + * registry. */ #define NODE_MODULE_VERSION 72