meta: merge node/master into node-chakracore/master

Merge 3b8da4c as of 2017-12-19
This commit was automatically generated. For any problems, please contact jackhorton

Reviewed-By: Taylor Woll <tawoll@ntdev.microsoft.com>

CONTRIBUTING.md

@@ -1,17 +1,15 @@
 # Contributing to Node.js
 
-Contributions to Node.js may come in many forms. Some contribute code changes,
-others contribute docs, others help answer questions from users, help keep the
-infrastructure running, or seek out ways of advocating for Node.js users of all
-types.
+Contributions to Node.js include code, documentation, answering user questions,
+running the project's infrastructure, and advocating for all types of Node.js
+users.
 
 The Node.js project welcomes all contributions from anyone willing to work in
-good faith both with other contributors and with the community. No contribution
-is too small and all contributions are valued.
+good faith with other contributors and the community. No contribution is too
+small and all contributions are valued.
 
-This guide details the basic steps for getting started contributing to the
-Node.js project's core `nodejs/node` GitHub Repository and describes what to
-expect throughout each step of the process.
+This guide explains the process for contributing to the Node.js project's core
+`nodejs/node` GitHub Repository and describes what to expect at each step.
 
 * [Code of Conduct](#code-of-conduct)
   * [Bad Actors](#bad-actors)

doc/api/assert.md

@@ -740,12 +740,15 @@ assert.throws(
 
 Validate error message using [`RegExp`][]:
 
+Using a regular expression runs `.toString` on the error object, and will
+therefore also include the error name.
+
 ```js
 assert.throws(
   () => {
     throw new Error('Wrong value');
   },
-  /value/
+  /^Error: Wrong value$/
 );
 ```
 
@@ -767,17 +770,42 @@ assert.throws(
 
 Note that `error` can not be a string. If a string is provided as the second
 argument, then `error` is assumed to be omitted and the string will be used for
-`message` instead. This can lead to easy-to-miss mistakes:
+`message` instead. This can lead to easy-to-miss mistakes. Please read the
+example below carefully if using a string as the second argument gets
+considered:
 
 <!-- eslint-disable no-restricted-syntax -->
 ```js
-// THIS IS A MISTAKE! DO NOT DO THIS!
-assert.throws(myFunction, 'missing foo', 'did not throw with expected message');
-
-// Do this instead.
-assert.throws(myFunction, /missing foo/, 'did not throw with expected message');
+function throwingFirst() {
+  throw new Error('First');
+}
+function throwingSecond() {
+  throw new Error('Second');
+}
+function notThrowing() {}
+
+// The second argument is a string and the input function threw an Error.
+// In that case both cases do not throw as neither is going to try to
+// match for the error message thrown by the input function!
+assert.throws(throwingFirst, 'Second');
+assert.throws(throwingSecond, 'Second');
+
+// The string is only used (as message) in case the function does not throw:
+assert.throws(notThrowing, 'Second');
+// AssertionError [ERR_ASSERTION]: Missing expected exception: Second
+
+// If it was intended to match for the error message do this instead:
+assert.throws(throwingSecond, /Second$/);
+// Does not throw because the error messages match.
+assert.throws(throwingFirst, /Second$/);
+// Throws a error:
+// Error: First
+//     at throwingFirst (repl:2:9)
 ```
 
+Due to the confusing notation, it is recommended not to use a string as the
+second argument. This might lead to difficult-to-spot errors.
+
 [`Error.captureStackTrace`]: errors.html#errors_error_capturestacktrace_targetobject_constructoropt
 [`Map`]: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Map
 [`Object.is()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is

doc/api/child_process.md

@@ -980,7 +980,7 @@ added: v0.1.90
 
 * `signal` {string}
 
-The `subprocess.kill()` methods sends a signal to the child process. If no
+The `subprocess.kill()` method sends a signal to the child process. If no
 argument is given, the process will be sent the `'SIGTERM'` signal. See
 signal(7) for a list of available signals.
 

doc/api/errors.md

@@ -810,6 +810,11 @@ Status code was outside the regular status code range (100-999).
 The `Trailer` header was set even though the transfer encoding does not support
 that.
 
+<a id="ERR_HTTP2_ALREADY_SHUTDOWN"></a>
+### ERR_HTTP2_ALREADY_SHUTDOWN
+
+Occurs with multiple attempts to shutdown an HTTP/2 session.
+
 <a id="ERR_HTTP2_CONNECT_AUTHORITY"></a>
 ### ERR_HTTP2_CONNECT_AUTHORITY
 
@@ -833,6 +838,12 @@ forbidden.
 
 A failure occurred sending an individual frame on the HTTP/2 session.
 
+<a id="ERR_HTTP2_GOAWAY_SESSION"></a>
+### ERR_HTTP2_GOAWAY_SESSION
+
+New HTTP/2 Streams may not be opened after the `Http2Session` has received a
+`GOAWAY` frame from the connected peer.
+
 <a id="ERR_HTTP2_HEADER_REQUIRED"></a>
 ### ERR_HTTP2_HEADER_REQUIRED
 
@@ -972,6 +983,11 @@ client.
 An attempt was made to use the `Http2Stream.prototype.responseWithFile()` API to
 send something other than a regular file.
 
+<a id="ERR_HTTP2_SESSION_ERROR"></a>
+### ERR_HTTP2_SESSION_ERROR
+
+The `Http2Session` closed with a non-zero error code.
+
 <a id="ERR_HTTP2_SOCKET_BOUND"></a>
 ### ERR_HTTP2_SOCKET_BOUND
 
@@ -989,10 +1005,11 @@ Use of the `101` Informational status code is forbidden in HTTP/2.
 An invalid HTTP status code has been specified. Status codes must be an integer
 between `100` and `599` (inclusive).
 
-<a id="ERR_HTTP2_STREAM_CLOSED"></a>
-### ERR_HTTP2_STREAM_CLOSED
+<a id="ERR_HTTP2_STREAM_CANCEL"></a>
+### ERR_HTTP2_STREAM_CANCEL
 
-An action was performed on an HTTP/2 Stream that had already been closed.
+An `Http2Stream` was destroyed before any data was transmitted to the connected
+peer.
 
 <a id="ERR_HTTP2_STREAM_ERROR"></a>
 ### ERR_HTTP2_STREAM_ERROR