doc: documentation deprecation of process.binding #22004
Conversation
This is the first step in a long process of deprecating `process.binding()` and replacing it with `internalBinding()`. Eventually, once we have replaced internal uses of `process.binding()` with `internalBinding()`, we can escalate to a runtime deprecation and eventual end-of-life.
nodejs-github-bot
added
deprecations
doc/api/deprecations.md
Outdated
| Type: Documentation-only | ||
|
|
||
| The `process.binding()` API is intended for use strictly by Node.js internal | ||
| code to provide a bridge between Node.js' JavaScript and native code layer. |
There was a problem hiding this comment.
It might be best to avoid the possessive by removing a couple words so it becomes: bridge between JavaScript and native code.
There was a problem hiding this comment.
Even better perhaps is remove everything after code from this sentence. You don't have to explain what the function does. That's superfluous information in this case.
doc/api/deprecations.md
Outdated
|
|
||
| The `process.binding()` API is intended for use strictly by Node.js internal | ||
| code to provide a bridge between Node.js' JavaScript and native code layer. | ||
| Use of `process.binding()` by user-land code is unsupported. |
There was a problem hiding this comment.
AFAIK, we use userland everywhere and user-land nowhere, so let's stick with userland.
doc/api/deprecations.md
Outdated
|
|
||
| Type: Documentation-only | ||
|
|
||
| The `process.binding()` API is intended for use strictly by Node.js internal |
There was a problem hiding this comment.
It's unnecessary. It's also imprecise. "only" would be more precise.
There was a problem hiding this comment.
So maybe this?:
process.binding()is intended for use by Node.js internal code only.
|
Putting all my nits together (and one or two that I didn't leave), the wording might be simplified to:
...or (adding one word more):
|
There was a problem hiding this comment.
We needed this for a long time.
Technically, it was never part of a documented public API afaik so we could just move to runtime deprecation, but given that the usage (of certain modules) was widespread, it seems to be a good decision to doc-deprecate it first.
|
@jasnell Perhaps DEP0103 text should be updated (in the «should be avoided» part) to mention this deprecation? |
|
I'd be great to make some things, like |
|
@jdalton can you please open an issue on how you use process.bindings(‘config’), and what would you need to have as a public API? Thanks! |
|
Will land this on Monday if there are no objections by then. |
doc/api/deprecations.md
Outdated
|
|
||
| Type: Documentation-only | ||
|
|
||
| The `process.binding()` API is intended for use by Node.js internal only |
There was a problem hiding this comment.
by Node.js internal only code -> by Node.js internal code only or only by Node.js internal code.
|
What about DEP0103? |
|
Ah, right, yeah I'll update the description for that |
This is the first step in a long process of deprecating `process.binding()` and replacing it with `internalBinding()`. Eventually, once we have replaced internal uses of `process.binding()` with `internalBinding()`, we can escalate to a runtime deprecation and eventual end-of-life. PR-URL: #22004 Reviewed-By: Gireesh Punathil <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Vladimir de Turckheim <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Bryan English <[email protected]> Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Gus Caplan <[email protected]> Reviewed-By: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: Tobias Nießen <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Michael Dawson <[email protected]>
|
Landed in 182051b |
|
@jasnell Is it supposed to include the deprecation codes as |
|
The deprecation number should be assigned when the PR is landed. |
|
Doh... Missed the step in landing. I used to have that in my local checks but I got rid of those when switching to node-core-util. Completely forgot about it. Will do a fixup pr |
|
It would be helpful if node-core-util could handle it :) |
|
Fixup here: #22062 |
Trott
added
the
notable-change
This is the first step in a long process of deprecating `process.binding()` and replacing it with `internalBinding()`. Eventually, once we have replaced internal uses of `process.binding()` with `internalBinding()`, we can escalate to a runtime deprecation and eventual end-of-life. PR-URL: #22004 Reviewed-By: Gireesh Punathil <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Vladimir de Turckheim <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Bryan English <[email protected]> Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Gus Caplan <[email protected]> Reviewed-By: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: Tobias Nießen <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Michael Dawson <[email protected]>
This is the first step in a long process of deprecating
process.binding()and replacing it withinternalBinding().Eventually, once we have replaced internal uses of
process.binding()withinternalBinding(), we can escalateto a runtime deprecation and eventual end-of-life.
/cc @nodejs/tsc @nodejs/security-wg
Checklist
make -j4 test(UNIX), orvcbuild test(Windows) passes