Skip to content

process: Add code to warnings, assign codes to deprecations

Rodrigo Muino Tomonari requested to merge github/fork/jasnell/warning-additions into master
Checklist
  • make -j8 test (UNIX), or vcbuild 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.

  1. 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 a code property on an Error object passed into process.emitWarning(). Within the process.on('warning') event handler, these can be accessed via the code property on the warning object.

  2. A new --redirect-warnings=file command line argument and matching NODE_REDIRECT_WARNINGS=file environment variable is added to allow process warning output to be printed to the given file as opposed to dumping to stderr. This will allow, for instance, npm and other applications spawning node process instances to capture warning output with less noise to the console.

  3. Every runtime and documentation-only deprecation in Node.js is assigned a static identifier code.

  4. 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

Merge request reports