doc: add ABI version registry

PR-URL: https://github.com/nodejs/node/pull/24114
Refs: https://nodejs.org/en/download/releases/
Refs: https://github.com/lgeiger/node-abi/blob/master/index.js
Refs: https://github.com/nodejs/TSC/issues/621
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Ujjwal Sharma <usharma1998@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Ali Ijaz Sheikh <ofrobots@google.com>

4 files changed, 84 insertions, 45 deletions

diff --git a/BUILDING.md b/BUILDING.md
index c363279ee5..61587317b7 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
+<https://github.com/nodejs/node/blob/master/doc/abi_version_registry.json>.
diff --git a/doc/abi_version_registry.json b/doc/abi_version_registry.json
new file mode 100644
index 0000000000..06a976d9af
--- /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 b03c623ecf..483b1f030c 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
+<https://github.com/nodejs/node/blob/master/doc/abi_version_registry.json>.
+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 349d73d18d..742ea6e62e 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