Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: add note about ABI compatibility #22237

Closed
wants to merge 1 commit into from
+11 −0
Closed

doc: add note about ABI compatibility #22237

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
11 changes: 11 additions & 0 deletions BUILDING.md
View file
Open in desktop
Expand Up @@ -528,3 +528,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
Copy link
Contributor

@ofrobots ofrobots Aug 10, 2018 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should flesh out a bit more what is involved in a custom NODE_MODULE_VERSION. The problem is that we don't necessarily have "room" in the incrementally increasing versions to anticipate needs apriori.

My proposal is:

  • Reserve 8 most significant bits in the NODE_MODULE_VERSION for 'distribution'.
  • Official builds would use 0. Electron, and other distributors could use a different value if the binary they are shipping is not ABI compatible.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

reserving a number of bits makes sense to me.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1. Does someone want to push a commit that adds this specific documentation?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ofrobots would you be able to supply explicit copy for this? Otherwise I'd like to land this in an iteration of this PR

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.