process: Add code to warnings, assign codes to deprecations
Checklist
-
make -j8 test
(UNIX), orvcbuild test nosign
(Windows) passes -
tests and/or benchmarks are included -
documentation is changed or added -
commit message follows commit guidelines
Affected core subsystem(s)
process, lib
Description of change
As discussed at the Node.js Interactive Collaboration Summit in Austin last week, this PR adds a few new capabilities that should make it easier to make dealing with runtime deprecation warnings in Node.js easier.
-
A static identifier code can be assigned to all process warnings. These are specified as either a new optional argument to
process.emitWarning()
or as acode
property on anError
object passed intoprocess.emitWarning()
. Within theprocess.on('warning')
event handler, these can be accessed via thecode
property on thewarning
object. -
A new
--redirect-warnings=file
command line argument and matchingNODE_REDIRECT_WARNINGS=file
environment variable is added to allow process warning output to be printed to the givenfile
as opposed to dumping tostderr
. This will allow, for instance, npm and other applications spawning node process instances to capture warning output with less noise to the console. -
Every runtime and documentation-only deprecation in Node.js is assigned a static identifier code.
-
A new deprecations.md file is added to the API documentation that lists each of the runtime and documentation-only deprecation codes assigned. For future work (perhaps a good first contribution for new Node.js contributors), it would be helpful to expand the details in deprecations.md to include links to the relevant sections in other parts of the API documentation as well as expanded descriptions of why the APIs are deprecated and what the alternatives are. /cc @nodejs/documentation
Note: This PR is currently semver-major because it adds improved type checking to the input on process.emitWarning()
to ensure that both the warning name and the identifier code are strings.
If this PR is backported to older Node.js release streams, the backport can be landed as a semver-minor if and only if the additional type checking on the name
argument is removed.
/cc @ashleygwilliams