doc: add note about ABI compatibility

Building node against versions of the dependencies that differ from the
ones we vendor will result in a non ABI compatible version of Node.js

This patch adds a note to make it explicit that if individuals build
node against different versions of a dependency they should make a
custom NODE_MODULE_VERSION.

PR-URL: https://github.com/nodejs/node/pull/22237
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Jon Moss <me@jonathanmoss.me>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

1 files changed, 11 insertions, 0 deletions

diff --git a/BUILDING.md b/BUILDING.md
index a5a66c680f2..7f07548eeae 100644
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -502,3 +502,14 @@ To make `./myModule.js` available via `require('myModule')` and
 ```console
 > .\vcbuild link-module './myModule.js' link-module './myModule2.js'
 ```
+
+## 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.