Repository navigation
Make warnings more beginner-friendly #11703
Description
This issue came up while discussing #11642
The problem with the warnings emitted by process.emitWarning is that they provide little information about the context or how to get more information. Unless the user knows about the cli flags like --trace-warnings or the warning API, there is no clue on how to proceed. A simple solution would be to append a short explanation like Use the --trace-warnings command line flag to get a full stack trace of this warning. if the flag is not set.
Activity
jhnns commentedon Mar 5, 2017
It's also surprising that the warnings are prefixed with
(${process.release.name}:${process.pid}). This makes sense when the output of multiple processes is piped into one destination, but it can be confusing in development mode, when the output is read by a human. To me, for instance, it was not clear that the number after:was the process id. I confused it with a line number. And you can only know that by guessing or reading node's source code 😁jhnns commentedon Mar 5, 2017
Related discussion: #9516
joyeecheung commentedon Mar 6, 2017
About the format for deprecations: I think adding a URL to anchors in https://github.com/nodejs/node/blob/master/doc/api/deprecations.md (or on the website once they get rendered) could be more helpful(if stderr is TTY, maybe).
The explanation of the format can be added to that document too (along with how to
--trace-deprecationand stuff).sam-github commentedon Mar 6, 2017
wrt. the idea of adding anchor URLs to node's deprecations page, note that the deprecation API is deliberately exported for use by thirdparty modules, so changes to make it work better for node users can't be too node-specific.
seishun commentedon Mar 11, 2017
@sam-github Which I think is a reason not to export the deprecation API.
Otherwise providing a URL in the deprecation message is a great idea. Listing all the deprecation-related flags would take up too much space.
jhnns commentedon Mar 13, 2017
👍
Seems reasonable. I'm just asking for a hint on how to proceed.
sam-github commentedon Apr 26, 2017
@jhnns the way to proceed is to PR an improvement to util.deprecate that includes useful information. People will have lots of comments, that's a good thing.
It may be that the changes are too large, and aren't backwards compatible. That's OK, if there is agreement that the messaging is much improved, then you'll just have to fork the util.deprecate API, make one in
lib/internal/...to be used only by Node, and the external API can be left there, unchanged.See: #12631 (comment)
Sorry for all the cross-linking, but the conversation spawns three threads ATM.
jasnell commentedon Apr 26, 2017
One possibility here is to add a new option to
process.emitWarning()for additionaldetail. This can be added to thewarningobject emitted byprocess.on('warning')using adetailproperty and can be included in the defaultstderroutput for all warnings. This would cover deprecations and warnings of all sorts.jasnell commentedon Apr 26, 2017
Also note that the
process.on('warning')API can easily be extended by third parties to provide additional capabilities. For instance, a module can easily attach a handler forDeprecationWarningthat outputs the additional URL link.Trott commentedon Aug 4, 2017
Should this remain open? (I can't tell.)
bnoordhuis commentedon Oct 5, 2017
Another two months passed with no activity. I'll close this out.