diff --git a/BUILDING.md b/BUILDING.md index 66c0ffc5aed226..525cbff3567e05 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -34,8 +34,8 @@ Support is divided into three tiers: ### Supported platforms The community does not build or test against end of life distributions (EoL). -Thus we do not recommend that you use Node on end of life or unsupported platforms -in production. +Thus we do not recommend that you use Node on end of life or unsupported +platforms in production. | System | Support type | Version | Architectures | Notes | |--------------|--------------|----------------------------------|----------------------|------------------| @@ -108,9 +108,11 @@ installed, you can find them under the menu `Xcode -> Open Developer Tool -> More Developer Tools...`. This step will install `clang`, `clang++`, and `make`. * After building, you may want to setup [firewall rules](tools/macosx-firewall.sh) -to avoid popups asking to accept incoming network connections when running tests: +to avoid popups asking to accept incoming network connections when running +tests: -If the path to your build directory contains a space, the build will likely fail. +If the path to your build directory contains a space, the build will likely +fail. ```console $ sudo ./tools/macosx-firewall.sh @@ -238,8 +240,8 @@ Prerequisites: * **Optional** (to build the MSI): the [WiX Toolset v3.11](http://wixtoolset.org/releases/) and the [Wix Toolset Visual Studio 2017 Extension](https://marketplace.visualstudio.com/items?itemName=RobMensching.WixToolsetVisualStudio2017Extension). -If the path to your build directory contains a space or a non-ASCII character, the -build will likely fail. +If the path to your build directory contains a space or a non-ASCII character, +the build will likely fail. ```console > .\vcbuild diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c3454adbfb93f..0cea182c55ccb6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,7 @@ # Node.js Changelog + + To make the changelog easier to both use and manage, it has been split into multiple files organized according to significant major and minor Node.js release lines. diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 584e598c2ff38c..e5d6421161aa52 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -56,7 +56,8 @@ or a pull request. Courtesy should always be shown to individuals submitting issues and pull requests to the Node.js project. Be welcoming to first-time contributors, -identified by the GitHub ![First-time contributor](./doc/first_timer_badge.png) badge. +identified by the GitHub ![First-time contributor](./doc/first_timer_badge.png) +badge. For first-time contributors, check if the commit author is the same as the pull request author, and ask if they have configured their git @@ -154,22 +155,23 @@ The pull request should have a CI status indicator if possible. #### Useful CI Jobs * [`node-test-pull-request`](https://ci.nodejs.org/job/node-test-pull-request/) -is the standard CI run we do to check Pull Requests. It triggers `node-test-commit`, -which runs the `build-ci` and `test-ci` targets on all supported platforms. +is the standard CI run we do to check Pull Requests. It triggers +`node-test-commit`, which runs the `build-ci` and `test-ci` targets on all +supported platforms. * [`node-test-linter`](https://ci.nodejs.org/job/node-test-linter/) -only runs the linter targets, which is useful for changes that only affect comments -or documentation. +only runs the linter targets, which is useful for changes that only affect +comments or documentation. * [`node-test-pull-request-lite`](https://ci.nodejs.org/job/node-test-pull-request-lite/) -only runs the linter job, as well as the tests on LinuxONE. Should only be used for -trivial changes that do not require being tested on all platforms. +only runs the linter job, as well as the tests on LinuxONE. Should only be used +for trivial changes that do not require being tested on all platforms. * [`citgm-smoker`](https://ci.nodejs.org/job/citgm-smoker/) -uses [`CitGM`](https://github.com/nodejs/citgm) to allow you to run `npm install && npm test` -on a large selection of common modules. This is useful to check whether a -change will cause breakage in the ecosystem. To test Node.JS ABI changes -you can run [`citgm-abi-smoker`](https://ci.nodejs.org/job/citgm-abi-smoker/). +uses [`CitGM`](https://github.com/nodejs/citgm) to allow you to run +`npm install && npm test` on a large selection of common modules. This is +useful to check whether a change will cause breakage in the ecosystem. To test +Node.JS ABI changes you can run [`citgm-abi-smoker`](https://ci.nodejs.org/job/citgm-abi-smoker/). * [`node-stress-single-test`](https://ci.nodejs.org/job/node-stress-single-test/) is designed to allow one to run a group of tests over and over on a specific @@ -480,8 +482,8 @@ Apply external patches: $ curl -L https://github.com/nodejs/node/pull/xxx.patch | git am --whitespace=fix ``` -If the merge fails even though recent CI runs were successful, then a 3-way merge may -be required. In this case try: +If the merge fails even though recent CI runs were successful, then a 3-way +merge may be required. In this case try: ```text $ git am --abort @@ -489,8 +491,9 @@ $ curl -L https://github.com/nodejs/node/pull/xxx.patch | git am -3 --whitespace ``` If the 3-way merge succeeds you can proceed, but make sure to check the changes against the original PR carefully and build/test on at least one platform -before landing. If the 3-way merge fails, then it is most likely that a conflicting -PR has landed since the CI run and you will have to ask the author to rebase. +before landing. If the 3-way merge fails, then it is most likely that a +conflicting PR has landed since the CI run and you will have to ask the author +to rebase. Check and re-review the changes: diff --git a/Makefile b/Makefile index 9ea385e46a362d..18da63f3ca8ee2 100644 --- a/Makefile +++ b/Makefile @@ -1005,13 +1005,17 @@ lint-md-clean: $(RM) -r tools/remark-preset-lint-node/node_modules $(RM) tools/.*mdlintstamp -lint-md-build: - @if [ ! -d tools/remark-cli/node_modules ]; then \ - echo "Markdown linter: installing remark-cli into tools/"; \ - cd tools/remark-cli && ../../$(NODE) ../../$(NPM) install; fi - @if [ ! -d tools/remark-preset-lint-node/node_modules ]; then \ - echo "Markdown linter: installing remark-preset-lint-node into tools/"; \ - cd tools/remark-preset-lint-node && ../../$(NODE) ../../$(NPM) install; fi +tools/remark-cli/node_modules: tools/remark-cli/package.json + @echo "Markdown linter: installing remark-cli into tools/" + @cd tools/remark-cli && $(call available-node,$(run-npm-install)) + +tools/remark-preset-lint-node/node_modules: \ + tools/remark-preset-lint-node/package.json + @echo "Markdown linter: installing remark-preset-lint-node into tools/" + @cd tools/remark-preset-lint-node && $(call available-node,$(run-npm-install)) + +lint-md-build: tools/remark-cli/node_modules \ + tools/remark-preset-lint-node/node_modules ifneq ("","$(wildcard tools/remark-cli/node_modules/)") LINT_MD_TARGETS = src lib benchmark tools/doc tools/icu diff --git a/README.md b/README.md index 89f9e3998a2827..521afa327e77c6 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,18 @@

- Node.js + Node.js

- + + +

Node.js is a JavaScript runtime built on Chrome's V8 JavaScript engine. Node.js diff --git a/doc/api/_toc.md b/doc/api/_toc.md index 420fb362fa537a..e8361d3de809f4 100644 --- a/doc/api/_toc.md +++ b/doc/api/_toc.md @@ -1,5 +1,5 @@ -@// NB(chrisdickinson): if you move this file, be sure to update tools/doc/html.js to -@// point at the new location. +@// NB(chrisdickinson): if you move this file, be sure to update +@// tools/doc/html.js to point at the new location. * [About these Docs](documentation.html) * [Usage & Example](synopsis.html) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 4fa23f28d116b0..7350c5596be50b 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -206,8 +206,8 @@ instance is destroyed. * `type` {string} The type of the async resource. * `triggerAsyncId` {number} The unique ID of the async resource in whose execution context this async resource was created. -* `resource` {Object} Reference to the resource representing the async operation, - needs to be released during _destroy_. +* `resource` {Object} Reference to the resource representing the async + operation, needs to be released during _destroy_. Called when a class is constructed that has the _possibility_ to emit an asynchronous event. This _does not_ mean the instance must call @@ -283,11 +283,11 @@ The `TCPSERVERWRAP` is the server which receives the connections. The `TCPWRAP` is the new connection from the client. When a new connection is made the `TCPWrap` instance is immediately constructed. This -happens outside of any JavaScript stack (side note: a `executionAsyncId()` of `0` -means it's being executed from C++, with no JavaScript stack above it). +happens outside of any JavaScript stack (side note: a `executionAsyncId()` of +`0` means it's being executed from C++, with no JavaScript stack above it). With only that information, it would be impossible to link resources together in -terms of what caused them to be created, so `triggerAsyncId` is given the task of -propagating what resource is responsible for the new resource's existence. +terms of what caused them to be created, so `triggerAsyncId` is given the task +of propagating what resource is responsible for the new resource's existence. ###### `resource` @@ -534,8 +534,8 @@ const server = net.createServer((conn) => { ## JavaScript Embedder API Library developers that handle their own asynchronous resources performing tasks -like I/O, connection pooling, or managing callback queues may use the `AsyncWrap` -JavaScript API so that all the appropriate callbacks are called. +like I/O, connection pooling, or managing callback queues may use the +`AsyncWrap` JavaScript API so that all the appropriate callbacks are called. ### `class AsyncResource()` @@ -647,8 +647,8 @@ never be called. #### `asyncResource.triggerAsyncId()` -* Returns: {number} The same `triggerAsyncId` that is passed to the `AsyncResource` -constructor. +* Returns: {number} The same `triggerAsyncId` that is passed to the +`AsyncResource` constructor. [`after` callback]: #async_hooks_after_asyncid [`before` callback]: #async_hooks_before_asyncid diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 3f827088ce5676..bd405b0f8c8121 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -1,6 +1,7 @@ # Buffer + > Stability: 2 - Stable diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 2aeae73c728228..56b40cd837ddc2 100755 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -1,6 +1,7 @@ # Child Process + > Stability: 2 - Stable diff --git a/doc/api/cluster.md b/doc/api/cluster.md index d0c801d53ee44e..3e65d9759c1ec8 100644 --- a/doc/api/cluster.md +++ b/doc/api/cluster.md @@ -269,8 +269,8 @@ changes: * Returns: {Worker} A reference to `worker`. -In a worker, this function will close all servers, wait for the `'close'` event on -those servers, and then disconnect the IPC channel. +In a worker, this function will close all servers, wait for the `'close'` event +on those servers, and then disconnect the IPC channel. In the master, an internal message is sent to the worker causing it to call `.disconnect()` on itself. @@ -280,8 +280,8 @@ Causes `.exitedAfterDisconnect` to be set. Note that after a server is closed, it will no longer accept new connections, but connections may be accepted by any other listening worker. Existing connections will be allowed to close as usual. When no more connections exist, -see [`server.close()`][], the IPC channel to the worker will close allowing it to -die gracefully. +see [`server.close()`][], the IPC channel to the worker will close allowing it +to die gracefully. The above applies *only* to server connections, client connections are not automatically closed by workers, and disconnect does not wait for them to close @@ -499,9 +499,9 @@ Emitted after the worker IPC channel has disconnected. This can occur when a worker exits gracefully, is killed, or is disconnected manually (such as with worker.disconnect()). -There may be a delay between the `'disconnect'` and `'exit'` events. These events -can be used to detect if the process is stuck in a cleanup or if there are -long-living connections. +There may be a delay between the `'disconnect'` and `'exit'` events. These +events can be used to detect if the process is stuck in a cleanup or if there +are long-living connections. ```js cluster.on('disconnect', (worker) => { @@ -673,7 +673,8 @@ Calls `.disconnect()` on each worker in `cluster.workers`. When they are disconnected all internal handles will be closed, allowing the master process to die gracefully if no other event is waiting. -The method takes an optional callback argument which will be called when finished. +The method takes an optional callback argument which will be called when +finished. This can only be called from the master process. diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 5813b44a71a396..ccf2fcd6448cbc 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -1167,8 +1167,8 @@ become deprecated in a future Node.js release. added: v6.0.0 --> -Property for checking and controlling whether a FIPS compliant crypto provider is -currently in use. Setting to true requires a FIPS build of Node.js. +Property for checking and controlling whether a FIPS compliant crypto provider +is currently in use. Setting to true requires a FIPS build of Node.js. ### crypto.createCipher(algorithm, password[, options]) - `prime` {string | Buffer | TypedArray | DataView} - `primeEncoding` {string} -- `generator` {number | string | Buffer | TypedArray | DataView} Defaults to `2`. +- `generator` {number | string | Buffer | TypedArray | DataView} Defaults to + `2`. - `generatorEncoding` {string} Creates a `DiffieHellman` key exchange object using the supplied `prime` and an @@ -1324,7 +1326,8 @@ otherwise a number, [`Buffer`][], `TypedArray`, or `DataView` is expected. added: v0.5.0 --> - `primeLength` {number} -- `generator` {number | string | Buffer | TypedArray | DataView} Defaults to `2`. +- `generator` {number | string | Buffer | TypedArray | DataView} Defaults to + `2`. Creates a `DiffieHellman` key exchange object and generates a prime of `primeLength` bits using an optional specific numeric `generator`. diff --git a/doc/api/debugger.md b/doc/api/debugger.md index b0da263f5947b4..e223ecfce2970c 100644 --- a/doc/api/debugger.md +++ b/doc/api/debugger.md @@ -8,8 +8,8 @@ Node.js includes an out-of-process debugging utility accessible via a [V8 Inspector][] and built-in debugging client. To use it, start Node.js -with the `inspect` argument followed by the path to the script to debug; a prompt -will be displayed indicating successful launch of the debugger: +with the `inspect` argument followed by the path to the script to debug; a +prompt will be displayed indicating successful launch of the debugger: ```txt $ node inspect myscript.js @@ -173,7 +173,8 @@ breakpoint) ### V8 Inspector Integration for Node.js V8 Inspector integration allows attaching Chrome DevTools to Node.js -instances for debugging and profiling. It uses the [Chrome Debugging Protocol][]. +instances for debugging and profiling. It uses the +[Chrome Debugging Protocol][]. V8 Inspector can be enabled by passing the `--inspect` flag when starting a Node.js application. It is also possible to supply a custom port with that flag, diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index a28df596d6919b..2549437ae3cac5 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -76,16 +76,16 @@ is strongly recommended: * [`Buffer.alloc(size[, fill[, encoding]])`][alloc] - Create a `Buffer` with *initialized* memory. -* [`Buffer.allocUnsafe(size)`][alloc_unsafe_size] - Create a `Buffer` with *uninitialized* - memory. +* [`Buffer.allocUnsafe(size)`][alloc_unsafe_size] - Create a `Buffer` with + *uninitialized* memory. * [`Buffer.allocUnsafeSlow(size)`][] - Create a `Buffer` with *uninitialized* memory. * [`Buffer.from(array)`][] - Create a `Buffer` with a copy of `array` -* [`Buffer.from(arrayBuffer[, byteOffset[, length]])`][from_arraybuffer] - Create a `Buffer` - that wraps the given `arrayBuffer`. +* [`Buffer.from(arrayBuffer[, byteOffset[, length]])`][from_arraybuffer] - + Create a `Buffer` that wraps the given `arrayBuffer`. * [`Buffer.from(buffer)`][] - Create a `Buffer` that copies `buffer`. -* [`Buffer.from(string[, encoding])`][from_string_encoding] - Create a `Buffer` that copies - `string`. +* [`Buffer.from(string[, encoding])`][from_string_encoding] - Create a `Buffer` + that copies `string`. ### DEP0006: child\_process options.customFds diff --git a/doc/api/dgram.md b/doc/api/dgram.md index e44bf3eea5a166..5f609856df8c29 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -394,8 +394,8 @@ added: v8.6.0 *Note: All references to scope in this section are referring to [IPv6 Zone Indices][], which are defined by [RFC 4007][]. In string form, an IP -with a scope index is written as `'IP%scope'` where scope is an interface name or -interface number.* +with a scope index is written as `'IP%scope'` where scope is an interface name +or interface number.* Sets the default outgoing multicast interface of the socket to a chosen interface or back to system interface selection. The `multicastInterface` must diff --git a/doc/api/dns.md b/doc/api/dns.md index c1ec1cfa51c41c..50456e62e4c884 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -145,8 +145,8 @@ changes: - `verbatim` {boolean} When `true`, the callback receives IPv4 and IPv6 addresses in the order the DNS resolver returned them. When `false`, IPv4 addresses are placed before IPv6 addresses. - **Default:** currently `false` (addresses are reordered) but this is expected - to change in the not too distant future. + **Default:** currently `false` (addresses are reordered) but this is + expected to change in the not too distant future. New code should use `{ verbatim: true }`. - `callback` {Function} - `err` {Error} diff --git a/doc/api/documentation.md b/doc/api/documentation.md index f78d7c1f40b572..2a422681d2fb14 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -85,8 +85,8 @@ like [`fs.open()`][], will document that. The docs link to the corresponding man pages (short for manual pages) which describe how the syscalls work. Some syscalls, like lchown(2), are BSD-specific. That means, for -example, that [`fs.lchown()`][] only works on macOS and other BSD-derived systems, -and is not available on Linux. +example, that [`fs.lchown()`][] only works on macOS and other BSD-derived +systems, and is not available on Linux. Most Unix syscalls have Windows equivalents, but behavior may differ on Windows relative to Linux and macOS. For an example of the subtle ways in which it's diff --git a/doc/api/domain.md b/doc/api/domain.md index 4c9136aea62cad..aa67d19fda992c 100644 --- a/doc/api/domain.md +++ b/doc/api/domain.md @@ -348,9 +348,9 @@ is emitted. The `enter` method is plumbing used by the `run`, `bind`, and `intercept` methods to set the active domain. It sets `domain.active` and `process.domain` to the domain, and implicitly pushes the domain onto the domain stack managed -by the domain module (see [`domain.exit()`][] for details on the domain stack). The -call to `enter` delimits the beginning of a chain of asynchronous calls and I/O -operations bound to a domain. +by the domain module (see [`domain.exit()`][] for details on the domain stack). +The call to `enter` delimits the beginning of a chain of asynchronous calls and +I/O operations bound to a domain. Calling `enter` changes only the active domain, and does not alter the domain itself. `enter` and `exit` can be called an arbitrary number of times on a diff --git a/doc/api/errors.md b/doc/api/errors.md index b43a3395bff615..a25766c096c5af 100755 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -227,7 +227,8 @@ Error.captureStackTrace(myObject); myObject.stack; // similar to `new Error().stack` ``` -The first line of the trace will be prefixed with `${myObject.name}: ${myObject.message}`. +The first line of the trace will be prefixed with `${myObject.name}: +${myObject.message}`. The optional `constructorOpt` argument accepts a function. If given, all frames above `constructorOpt`, including `constructorOpt`, will be omitted from the diff --git a/doc/api/events.md b/doc/api/events.md index 8eaa8cae102b75..b42eff6fcac865 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -515,10 +515,10 @@ listener array for the specified `eventName`, then `removeListener` must be called multiple times to remove each instance. Note that once an event has been emitted, all listeners attached to it at the -time of emitting will be called in order. This implies that any `removeListener()` -or `removeAllListeners()` calls *after* emitting and *before* the last listener -finishes execution will not remove them from `emit()` in progress. Subsequent -events will behave as expected. +time of emitting will be called in order. This implies that any +`removeListener()` or `removeAllListeners()` calls *after* emitting and +*before* the last listener finishes execution will not remove them from +`emit()` in progress. Subsequent events will behave as expected. ```js const myEmitter = new MyEmitter(); diff --git a/doc/api/fs.md b/doc/api/fs.md index 1eaae690190c70..457995779b4e0e 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -225,8 +225,8 @@ added: v0.5.8 Objects returned from [`fs.watch()`][] are of this type. -The `listener` callback provided to `fs.watch()` receives the returned FSWatcher's -`change` events. +The `listener` callback provided to `fs.watch()` receives the returned +FSWatcher's `change` events. The object itself emits these events: @@ -2288,8 +2288,8 @@ changes: Synchronous rmdir(2). Returns `undefined`. -*Note*: Using `fs.rmdirSync()` on a file (not a directory) results in an `ENOENT` -error on Windows and an `ENOTDIR` error on POSIX. +*Note*: Using `fs.rmdirSync()` on a file (not a directory) results in an +`ENOENT` error on Windows and an `ENOTDIR` error on POSIX. ## fs.stat(path, callback) * `options` {Object} A set of options providing information for name generation - * `host` {string} A domain name or IP address of the server to issue the request to + * `host` {string} A domain name or IP address of the server to issue the + request to * `port` {number} Port of remote server * `localAddress` {string} Local interface to bind for network connections when issuing the request @@ -330,9 +331,9 @@ added: v0.7.0 * `socket` {net.Socket} * `head` {Buffer} -Emitted each time a server responds to a request with a `CONNECT` method. If this -event is not being listened for, clients receiving a `CONNECT` method will have -their connections closed. +Emitted each time a server responds to a request with a `CONNECT` method. If +this event is not being listened for, clients receiving a `CONNECT` method will +have their connections closed. A client and server pair demonstrating how to listen for the `'connect'` event: @@ -623,7 +624,8 @@ added: v0.5.9 --> * `timeout` {number} Milliseconds before a request times out. -* `callback` {Function} Optional function to be called when a timeout occurs. Same as binding to the `timeout` event. +* `callback` {Function} Optional function to be called when a timeout occurs. + Same as binding to the `timeout` event. Once a socket is assigned to this request and is connected [`socket.setTimeout()`][] will be called. @@ -688,7 +690,8 @@ Returns `request`. added: v0.1.17 --> -This class inherits from [`net.Server`][] and has the following additional events: +This class inherits from [`net.Server`][] and has the following additional +events: ### Event: 'checkContinue' Sends a HTTP/1.1 100 Continue message to the client, indicating that -the request body should be sent. See the [`'checkContinue'`][] event on `Server`. +the request body should be sent. See the [`'checkContinue'`][] event on +`Server`. ### response.writeHead(statusCode[, statusMessage][, headers]) -An Agent object for HTTPS similar to [`http.Agent`][]. See [`https.request()`][] -for more information. +An Agent object for HTTPS similar to [`http.Agent`][]. See +[`https.request()`][] for more information. ## Class: https.Server -- `options` {Object} Accepts `options` from [`tls.createServer()`][] and [`tls.createSecureContext()`][]. +- `options` {Object} Accepts `options` from [`tls.createServer()`][] and + [`tls.createSecureContext()`][]. - `requestListener` {Function} A listener to be added to the `request` event. Example: @@ -154,8 +155,8 @@ changes: pr-url: https://github.com/nodejs/node/pull/10638 description: The `options` parameter can be a WHATWG `URL` object. --> -- `options` {Object | string | URL} Accepts all `options` from [`http.request()`][], - with some differences in default values: +- `options` {Object | string | URL} Accepts all `options` from + [`http.request()`][], with some differences in default values: - `protocol` Defaults to `https:` - `port` Defaults to `443`. - `agent` Defaults to `https.globalAgent`. @@ -164,9 +165,9 @@ changes: Makes a request to a secure web server. -The following additional `options` from [`tls.connect()`][] are also accepted when using a - custom [`Agent`][]: - `pfx`, `key`, `passphrase`, `cert`, `ca`, `ciphers`, `rejectUnauthorized`, `secureProtocol`, `servername` +The following additional `options` from [`tls.connect()`][] are also accepted + when using a custom [`Agent`][]: `pfx`, `key`, `passphrase`, `cert`, `ca`, + `ciphers`, `rejectUnauthorized`, `secureProtocol`, `servername` `options` can be an object, a string, or a [`URL`][] object. If `options` is a string, it is automatically parsed with [`url.parse()`][]. If it is a [`URL`][] diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 0843165f075be9..dd04f589a1e84b 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -139,9 +139,9 @@ create a scope before invoking any functions that can result in the creation of JavaScript values. Handle scopes are created using [`napi_open_handle_scope`][] and are destroyed -using [`napi_close_handle_scope`][]. Closing the scope can indicate to the GC that -all `napi_value`s created during the lifetime of the handle scope are no longer -referenced from the current stack frame. +using [`napi_close_handle_scope`][]. Closing the scope can indicate to the GC +that all `napi_value`s created during the lifetime of the handle scope are no +longer referenced from the current stack frame. For more details, review the [Object Lifetime Management][]. @@ -646,7 +646,8 @@ current scope and the lifespan of the handle changes from the current scope to that of the outer scope. The methods available to open/close escapable scopes are -[`napi_open_escapable_handle_scope`][] and [`napi_close_escapable_handle_scope`][]. +[`napi_open_escapable_handle_scope`][] and +[`napi_close_escapable_handle_scope`][]. The request to promote a handle is made through [`napi_escape_handle`][] which can only be called once. @@ -1347,8 +1348,8 @@ TypedArray objects provide an array-like view over an underlying data buffer where each element has the same underlying binary scalar datatype. It's required that (length * size_of_element) + byte_offset should -be <= the size in bytes of the array passed in. If not, a RangeError exception is -raised. +be <= the size in bytes of the array passed in. If not, a RangeError exception +is raised. JavaScript TypedArray Objects are described in [Section 22.2](https://tc39.github.io/ecma262/#sec-typedarray-objects) @@ -1601,10 +1602,11 @@ its length. *WARNING*: Use caution while using this API. The lifetime of the underlying data buffer is managed by the ArrayBuffer even after it's returned. A -possible safe way to use this API is in conjunction with [`napi_create_reference`][], -which can be used to guarantee control over the lifetime of the -ArrayBuffer. It's also safe to use the returned data buffer within the same -callback as long as there are no calls to other APIs that might trigger a GC. +possible safe way to use this API is in conjunction with +[`napi_create_reference`][], which can be used to guarantee control over the +lifetime of the ArrayBuffer. It's also safe to use the returned data buffer +within the same callback as long as there are no calls to other APIs that might +trigger a GC. #### *napi_get_buffer_info* + > Stability: 2 - Stable diff --git a/doc/api/process.md b/doc/api/process.md index 41067744af1f03..7057e7fcf92c64 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -199,9 +199,10 @@ of allocated resources (e.g. file descriptors, handles, etc) before shutting down the process. **It is not safe to resume normal operation after `'uncaughtException'`.** -To restart a crashed application in a more reliable way, whether `uncaughtException` -is emitted or not, an external monitor should be employed in a separate process -to detect application failures and recover or restart as needed. +To restart a crashed application in a more reliable way, whether +`uncaughtException` is emitted or not, an external monitor should be employed +in a separate process to detect application failures and recover or restart as +needed. ### Event: 'unhandledRejection' * `options` {Object} - * `rejectUnauthorized` {boolean} If not `false`, the server certificate is verified - against the list of supplied CAs. An `'error'` event is emitted if + * `rejectUnauthorized` {boolean} If not `false`, the server certificate is + verified against the list of supplied CAs. An `'error'` event is emitted if verification fails; `err.code` contains the OpenSSL error code. Defaults to `true`. * `requestCert` @@ -761,13 +761,14 @@ failure. On success, returns {undefined}. *Note*: This function can be overwritten by providing alternative function as part of the `options.checkServerIdentity` option passed to `tls.connect()`. -The overwriting function can call `tls.checkServerIdentity()` of course, to augment -the checks done with additional verification. +The overwriting function can call `tls.checkServerIdentity()` of course, to +augment the checks done with additional verification. -*Note*: This function is only called if the certificate passed all other checks, such as -being issued by trusted CA (`options.ca`). +*Note*: This function is only called if the certificate passed all other checks, +such as being issued by trusted CA (`options.ca`). -The cert object contains the parsed certificate and will have a structure similar to: +The cert object contains the parsed certificate and will have a structure +similar to: ```text { subject: @@ -827,8 +828,8 @@ changes: connection/disconnection/destruction of `socket` is the user's responsibility, calling `tls.connect()` will not cause `net.connect()` to be called. - * `rejectUnauthorized` {boolean} If not `false`, the server certificate is verified - against the list of supplied CAs. An `'error'` event is emitted if + * `rejectUnauthorized` {boolean} If not `false`, the server certificate is + verified against the list of supplied CAs. An `'error'` event is emitted if verification fails; `err.code` contains the OpenSSL error code. Defaults to `true`. * `NPNProtocols` {string[]|Buffer[]|Uint8Array[]|Buffer|Uint8Array} @@ -980,7 +981,8 @@ changes: as an array of unencrypted PFX buffers, or an array of objects in the form `{buf: [, passphrase: ]}`. The object form can only occur in an array. `object.passphrase` is optional. Encrypted PFX will be - decrypted with `object.passphrase` if provided, or `options.passphrase` if it is not. + decrypted with `object.passphrase` if provided, or `options.passphrase` if + it is not. * `key` {string|string[]|Buffer|Buffer[]|Object[]} Optional private keys in PEM format. PEM allows the option of private keys being encrypted. Encrypted keys will be decrypted with `options.passphrase`. Multiple keys using @@ -1278,8 +1280,8 @@ changes: opened as a server. * `requestCert` {boolean} `true` to specify whether a server should request a certificate from a connecting client. Only applies when `isServer` is `true`. -* `rejectUnauthorized` {boolean} If not `false` a server automatically reject clients - with invalid certificates. Only applies when `isServer` is `true`. +* `rejectUnauthorized` {boolean} If not `false` a server automatically reject + clients with invalid certificates. Only applies when `isServer` is `true`. * `options` * `secureContext`: An optional TLS context object from [`tls.createSecureContext()`][] diff --git a/doc/api/tracing.md b/doc/api/tracing.md index e03477b1adf20c..a9c652967eeec8 100644 --- a/doc/api/tracing.md +++ b/doc/api/tracing.md @@ -5,12 +5,13 @@ Trace Event provides a mechanism to centralize tracing information generated by V8, Node core, and userspace code. -Tracing can be enabled by passing the `--trace-events-enabled` flag when starting a -Node.js application. +Tracing can be enabled by passing the `--trace-events-enabled` flag when +starting a Node.js application. The set of categories for which traces are recorded can be specified using the -`--trace-event-categories` flag followed by a list of comma separated category names. -By default the `node`, `node.async_hooks`, and `v8` categories are enabled. +`--trace-event-categories` flag followed by a list of comma separated category +names. By default the `node`, `node.async_hooks`, and `v8` categories are +enabled. ```txt node --trace-events-enabled --trace-event-categories v8,node,node.async_hooks server.js diff --git a/doc/api/util.md b/doc/api/util.md index 52e9e41639e0ca..d00d365d4ea41c 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -113,8 +113,8 @@ environment variable. For example: `NODE_DEBUG=fs,net,tls`. added: v0.8.0 --> -The `util.deprecate()` method wraps the given `function` or class in such a way that -it is marked as deprecated. +The `util.deprecate()` method wraps the given `function` or class in such a way +that it is marked as deprecated. ```js @@ -176,12 +176,14 @@ corresponding argument. Supported placeholders are: contains circular references. * `%o` - Object. A string representation of an object with generic JavaScript object formatting. - Similar to `util.inspect()` with options `{ showHidden: true, depth: 4, showProxy: true }`. - This will show the full object including non-enumerable symbols and properties. + Similar to `util.inspect()` with options + `{ showHidden: true, depth: 4, showProxy: true }`. This will show the full + object including non-enumerable symbols and properties. * `%O` - Object. A string representation of an object with generic JavaScript object formatting. Similar to `util.inspect()` without options. - This will show the full object not including non-enumerable symbols and properties. + This will show the full object not including non-enumerable symbols and + properties. * `%%` - single percent sign (`'%'`). This does not consume an argument. If the placeholder does not have a corresponding argument, the placeholder is @@ -529,7 +531,8 @@ console.log(promisified === doSomething[util.promisify.custom]); This can be useful for cases where the original function does not follow the standard format of taking an error-first callback as the last argument. -For example, with a function that takes in `(foo, onSuccessCallback, onErrorCallback)`: +For example, with a function that takes in +`(foo, onSuccessCallback, onErrorCallback)`: ```js doSomething[util.promisify.custom] = (foo) => { diff --git a/doc/api/v8.md b/doc/api/v8.md index 3684a61583cb37..300b1afc30493b 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -110,11 +110,11 @@ Returns an object with the following properties: * `peak_malloced_memory` {number} * `does_zap_garbage` {number} -`does_zap_garbage` is a 0/1 boolean, which signifies whether the `--zap_code_space` -option is enabled or not. This makes V8 overwrite heap garbage with a bit -pattern. The RSS footprint (resident memory set) gets bigger because it -continuously touches all heap pages and that makes them less likely to get -swapped out by the operating system. +`does_zap_garbage` is a 0/1 boolean, which signifies whether the +`--zap_code_space` option is enabled or not. This makes V8 overwrite heap +garbage with a bit pattern. The RSS footprint (resident memory set) gets bigger +because it continuously touches all heap pages and that makes them less likely +to get swapped out by the operating system. For example: @@ -302,7 +302,8 @@ added: v8.0.0 #### new Deserializer(buffer) -* `buffer` {Buffer|Uint8Array} A buffer returned by [`serializer.releaseBuffer()`][]. +* `buffer` {Buffer|Uint8Array} A buffer returned by + [`serializer.releaseBuffer()`][]. Creates a new `Deserializer` object. diff --git a/doc/api/vm.md b/doc/api/vm.md index 41101a5e5cf76f..b136a35cee9cec 100644 --- a/doc/api/vm.md +++ b/doc/api/vm.md @@ -455,9 +455,9 @@ local scope, so the value `localVar` is changed. In this way ## Example: Running an HTTP Server within a VM -When using either [`script.runInThisContext()`][] or [`vm.runInThisContext()`][], the -code is executed within the current V8 global context. The code passed -to this VM context will have its own isolated scope. +When using either [`script.runInThisContext()`][] or +[`vm.runInThisContext()`][], the code is executed within the current V8 global +context. The code passed to this VM context will have its own isolated scope. In order to run a simple web server using the `http` module the code passed to the context must either call `require('http')` on its own, or have a reference diff --git a/doc/api/zlib.md b/doc/api/zlib.md index 7c55b94b26706b..a44c3c1cde5712 100644 --- a/doc/api/zlib.md +++ b/doc/api/zlib.md @@ -308,8 +308,8 @@ ignored by the decompression classes. * `level` {integer} (compression only) * `memLevel` {integer} (compression only) * `strategy` {integer} (compression only) -* `dictionary` {Buffer|TypedArray|DataView} (deflate/inflate only, empty dictionary by - default) +* `dictionary` {Buffer|TypedArray|DataView} (deflate/inflate only, empty + dictionary by default) * `info` {boolean} (If `true`, returns an object with `buffer` and `engine`) See the description of `deflateInit2` and `inflateInit2` at diff --git a/doc/changelogs/CHANGELOG_ARCHIVE.md b/doc/changelogs/CHANGELOG_ARCHIVE.md index 578f69292837a6..5dabc49b52f929 100644 --- a/doc/changelogs/CHANGELOG_ARCHIVE.md +++ b/doc/changelogs/CHANGELOG_ARCHIVE.md @@ -1,6 +1,7 @@ # Node.js ChangeLog Archive + diff --git a/doc/changelogs/CHANGELOG_IOJS.md b/doc/changelogs/CHANGELOG_IOJS.md index 602982f4bfcac7..44f463f0f52c31 100644 --- a/doc/changelogs/CHANGELOG_IOJS.md +++ b/doc/changelogs/CHANGELOG_IOJS.md @@ -1,6 +1,7 @@ # io.js ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V010.md b/doc/changelogs/CHANGELOG_V010.md index 3efbbd7b9d9cf0..a227bf440dabe7 100644 --- a/doc/changelogs/CHANGELOG_V010.md +++ b/doc/changelogs/CHANGELOG_V010.md @@ -1,6 +1,7 @@ # Node.js 0.10 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V012.md b/doc/changelogs/CHANGELOG_V012.md index 1b67db58708b89..8e0cd1f1b1871d 100644 --- a/doc/changelogs/CHANGELOG_V012.md +++ b/doc/changelogs/CHANGELOG_V012.md @@ -1,6 +1,7 @@ # Node.js 0.12 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V4.md b/doc/changelogs/CHANGELOG_V4.md index 608b8f802f276b..43b00bbfdbe729 100644 --- a/doc/changelogs/CHANGELOG_V4.md +++ b/doc/changelogs/CHANGELOG_V4.md @@ -1,6 +1,7 @@ # Node.js 4 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V5.md b/doc/changelogs/CHANGELOG_V5.md index 1ced8522440b82..87a0954f7a2af3 100644 --- a/doc/changelogs/CHANGELOG_V5.md +++ b/doc/changelogs/CHANGELOG_V5.md @@ -1,6 +1,7 @@ # Node.js 5 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V6.md b/doc/changelogs/CHANGELOG_V6.md index a5b7faca278cd4..d77c054b55e274 100644 --- a/doc/changelogs/CHANGELOG_V6.md +++ b/doc/changelogs/CHANGELOG_V6.md @@ -1,6 +1,7 @@ # Node.js 6 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V7.md b/doc/changelogs/CHANGELOG_V7.md index fb959b947c40a5..2597c26adcdabc 100644 --- a/doc/changelogs/CHANGELOG_V7.md +++ b/doc/changelogs/CHANGELOG_V7.md @@ -1,6 +1,7 @@ # Node.js 7 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V8.md b/doc/changelogs/CHANGELOG_V8.md index 7797a76edafbf5..5301d844722bcf 100644 --- a/doc/changelogs/CHANGELOG_V8.md +++ b/doc/changelogs/CHANGELOG_V8.md @@ -1,6 +1,7 @@ # Node.js 8 ChangeLog +
diff --git a/doc/guides/building-node-with-ninja.md b/doc/guides/building-node-with-ninja.md index 29b32c3d7277de..f7af465144617a 100644 --- a/doc/guides/building-node-with-ninja.md +++ b/doc/guides/building-node-with-ninja.md @@ -1,6 +1,8 @@ # Building Node with Ninja -The purpose of this guide is to show how to build Node.js using [Ninja][], as doing so can be significantly quicker than using `make`. Please see [Ninja's site][Ninja] for installation instructions (unix only). +The purpose of this guide is to show how to build Node.js using [Ninja][], as +doing so can be significantly quicker than using `make`. Please see +[Ninja's site][Ninja] for installation instructions (unix only). To build Node with ninja, there are 3 steps that must be taken: @@ -8,31 +10,38 @@ To build Node with ninja, there are 3 steps that must be taken: 2. Run `ninja -C out/Release` to produce a compiled release binary. 3. Lastly, make symlink to `./node` using `ln -fs out/Release/node node`. -When running `ninja -C out/Release` you will see output similar to the following if the build has succeeded: +When running `ninja -C out/Release` you will see output similar to the +following if the build has succeeded: ```txt ninja: Entering directory `out/Release` [4/4] LINK node, POSTBUILDS ``` -The bottom line will change while building, showing the progress as `[finished/total]` build steps. -This is useful output that `make` does not produce and is one of the benefits of using Ninja. -Also, Ninja will likely compile much faster than even `make -j4` (or `-j`). +The bottom line will change while building, showing the progress as +`[finished/total]` build steps. This is useful output that `make` does not +produce and is one of the benefits of using Ninja. Also, Ninja will likely +compile much faster than even `make -j4` +(or `-j`). ## Considerations -Ninja builds vary slightly from `make` builds. If you wish to run `make test` after, `make` will likely still need to rebuild some amount of Node. +Ninja builds vary slightly from `make` builds. If you wish to run `make test` +after, `make` will likely still need to rebuild some amount of Node. -As such, if you wish to run the tests, it can be helpful to invoke the test runner directly, like so: +As such, if you wish to run the tests, it can be helpful to invoke the test +runner directly, like so: `tools/test.py --mode=release message parallel sequential -J` ## Alias -`alias nnode='./configure --ninja && ninja -C out/Release && ln -fs out/Release/node node'` +`alias nnode='./configure --ninja && ninja -C out/Release && ln -fs +out/Release/node node'` ## Producing a debug build -The above alias can be modified slightly to produce a debug build, rather than a release build as shown below: -`alias nnodedebug='./configure --ninja && ninja -C out/Debug && ln -fs out/Debug/node node_g'` +The above alias can be modified slightly to produce a debug build, rather than +a release build as shown below: `alias nnodedebug='./configure --ninja && ninja +-C out/Debug && ln -fs out/Debug/node node_g'` [Ninja]: https://ninja-build.org/ diff --git a/doc/guides/maintaining-V8.md b/doc/guides/maintaining-V8.md index 30300d402b3a9a..d41daa58f32119 100644 --- a/doc/guides/maintaining-V8.md +++ b/doc/guides/maintaining-V8.md @@ -15,24 +15,37 @@ Node.js and V8 teams at Google can help. ## V8 Release Schedule -V8 and Chromium follow a [roughly 6-week release cadence](https://www.chromium.org/developers/calendar). At any given time there are three V8 branches that are **active**. +V8 and Chromium follow a [roughly 6-week release cadence](https://www.chromium.org/developers/calendar). +At any given time there are three V8 branches that are **active**. For example, at the time of this writing: -* **Stable**: V8 5.4 is currently shipping as part of Chromium stable. This branch was created approx. 6 weeks before from when V8 5.3 shipped as stable. -* **Beta**: V8 5.5 is currently in beta. It will be promoted to stable next; approximately 6 weeks after V8 5.4 shipped as stable. -* **Master**: V8 tip-of-tree corresponds to V8 5.6. This branch gets regularly released as part of the Chromium **canary** builds. This branch will be promoted to beta next when V8 5.5 ships as stable. +* **Stable**: V8 5.4 is currently shipping as part of Chromium stable. This + branch was created approx. 6 weeks before from when V8 5.3 shipped as stable. +* **Beta**: V8 5.5 is currently in beta. It will be promoted to stable next; + approximately 6 weeks after V8 5.4 shipped as stable. +* **Master**: V8 tip-of-tree corresponds to V8 5.6. This branch gets regularly + released as part of the Chromium **canary** builds. This branch will be + promoted to beta next when V8 5.5 ships as stable. All older branches are abandoned and are not maintained by the V8 team. ### V8 merge process overview -The process for backporting bug fixes to active branches is officially documented [on the V8 wiki](https://github.com/v8/v8/wiki/Merging%20&%20Patching). The summary of the process is: - -* V8 only supports active branches. There is no testing done on any branches older than the current stable/beta/master. -* A fix needing backport is tagged w/ *merge-request-x.x* tag. This can be done by anyone interested in getting the fix backported. Issues with this tag are reviewed by the V8 team regularly as candidates for backporting. -* Fixes need some 'baking time' before they can be approved for backporting. This means waiting a few days to ensure that no issues are detected on the canary/beta builds. -* Once ready, the issue is tagged w/ *merge-approved-x.x* and one can do the actual merge by using the scripts on the [wiki page](https://github.com/v8/v8/wiki/Merging%20&%20Patching). +The process for backporting bug fixes to active branches is officially +documented [on the V8 wiki](https://github.com/v8/v8/wiki/Merging%20&%20Patching). +The summary of the process is: + +* V8 only supports active branches. There is no testing done on any branches + older than the current stable/beta/master. +* A fix needing backport is tagged w/ *merge-request-x.x* tag. This can be + done by anyone interested in getting the fix backported. Issues with this tag + are reviewed by the V8 team regularly as candidates for backporting. +* Fixes need some 'baking time' before they can be approved for backporting. + This means waiting a few days to ensure that no issues are detected on the + canary/beta builds. +* Once ready, the issue is tagged w/ *merge-approved-x.x* and one can do the + actual merge by using the scripts on the [wiki page](https://github.com/v8/v8/wiki/Merging%20&%20Patching). * Merge requests to an abandoned branch will be rejected. * Only bug fixes are accepted for backporting. @@ -146,44 +159,70 @@ process. * Fixed, but needs backport. The bug may need porting to one or more branches. * Backporting to active branches. * Backporting to abandoned branches. -* Backports identified by the V8 team. Bugs identified by upstream V8 that we haven't encountered in Node.js yet. +* Backports identified by the V8 team. Bugs identified by upstream V8 that we + haven't encountered in Node.js yet. ### Unfixed Upstream Bugs -If the bug can be reproduced on the [`vee-eight-lkgr` branch](https://github.com/v8/node/tree/vee-eight-lkgr), Chromium canary, or V8 tip-of-tree, and the test case is valid, then the bug needs to be fixed upstream first. +If the bug can be reproduced on the [`vee-eight-lkgr` branch](https://github.com/v8/node/tree/vee-eight-lkgr), +Chromium canary, or V8 tip-of-tree, and the test case is valid, then the bug +needs to be fixed upstream first. * Start by opening a bug upstream [using this template](https://bugs.chromium.org/p/v8/issues/entry?template=Node.js%20upstream%20bug). -* Make sure to include a link to the corresponding Node.js issue (if one exists). -* If the fix is simple enough, you may fix it yourself; [contributions](https://github.com/v8/v8/wiki/Contributing) are welcome. +* Make sure to include a link to the corresponding Node.js issue + (if one exists). +* If the fix is simple enough, you may fix it yourself; [contributions](https://github.com/v8/v8/wiki/Contributing) + are welcome. * V8's build waterfall tests your change. -* Once the bug is fixed it may still need backporting, if it exists in other V8 branches that are still active or are branches that Node.js cares about. Follow the process for backporting below. +* Once the bug is fixed it may still need backporting, if it exists in other V8 + branches that are still active or are branches that Node.js cares about. + Follow the process for backporting below. ### Backporting to Active Branches -If the bug exists in any of the active V8 branches, we may need to get the fix backported. At any given time there are [two active branches](https://build.chromium.org/p/client.v8.branches/console) (beta and stable) in addition to master. The following steps are needed to backport the fix: +If the bug exists in any of the active V8 branches, we may need to get the fix +backported. At any given time there are [two active branches](https://build.chromium.org/p/client.v8.branches/console) +(beta and stable) in addition to master. The following steps are needed to +backport the fix: * Identify which version of V8 the bug was fixed in. * Identify if any active V8 branches still contain the bug: * A tracking bug is needed to request a backport. - * If there isn't already a V8 bug tracking the fix, open a new merge request bug using this [Node.js specific template](https://bugs.chromium.org/p/v8/issues/entry?template=Node.js%20merge%20request). + * If there isn't already a V8 bug tracking the fix, open a new merge + request bug using this [Node.js specific template](https://bugs.chromium.org/p/v8/issues/entry?template=Node.js%20merge%20request). * If a bug already exists * Add a reference to the GitHub issue. - * Attach *merge-request-x.x* labels to the bug for any active branches that still contain the bug. (e.g. merge-request-5.3, merge-request-5.4) + * Attach *merge-request-x.x* labels to the bug for any active branches + that still contain the bug. (e.g. merge-request-5.3, merge-request-5.4) * Add ofrobots-at-google.com to the cc list. -* Once the merge has been approved, it should be merged using the [merge script documented in the V8 wiki](https://github.com/v8/v8/wiki/Merging%20&%20Patching). Merging requires commit access to the V8 repository. If you don't have commit access you can indicate someone on the V8 team can do the merge for you. -* It is possible that the merge request may not get approved, for example if it is considered to be a feature or otherwise too risky for V8 stable. In such cases we float the patch on the Node.js side. See the process on 'Backporting to Abandoned branches'. -* Once the fix has been merged upstream, it can be picked up during an update of the V8 branch, (see below). +* Once the merge has been approved, it should be merged using the +[merge script documented in the V8 wiki](https://github.com/v8/v8/wiki/Merging%20&%20Patching). +Merging requires commit access to the V8 repository. If you don't have commit +access you can indicate someone on the V8 team can do the merge for you. +* It is possible that the merge request may not get approved, for example if it +is considered to be a feature or otherwise too risky for V8 stable. In such +cases we float the patch on the Node.js side. See the process on 'Backporting +to Abandoned branches'. +* Once the fix has been merged upstream, it can be picked up during an update +of the V8 branch, (see below). ### Backporting to Abandoned Branches Abandoned V8 branches are supported in the Node.js V8 repository. The fix needs to be cherry-picked in the Node.js repository and V8-CI must test the change. -* For each abandoned V8 branch corresponding to an LTS branch that is affected by the bug: - * Open a cherry-pick PR on nodejs/node targeting the appropriate *vY.x-staging* branch (e.g. *v6.x-staging* to fix an issue in V8-5.1). - * Increase the patch level version in `v8-version.h`. This will not cause any problems with versioning because V8 will not publish other patches for this branch, so Node.js can effectively bump the patch version. - * In some cases the patch may require extra effort to merge in case V8 has changed substantially. For important issues we may be able to lean on the V8 team to get help with reimplementing the patch. - * Run the Node.js [V8-CI](https://ci.nodejs.org/job/node-test-commit-v8-linux/) in addition to the [Node.js CI](https://ci.nodejs.org/job/node-test-pull-request/). +* For each abandoned V8 branch corresponding to an LTS branch that is affected + by the bug: + * Open a cherry-pick PR on nodejs/node targeting the appropriate + *vY.x-staging* branch (e.g. *v6.x-staging* to fix an issue in V8-5.1). + * Increase the patch level version in `v8-version.h`. This will not cause + any problems with versioning because V8 will not publish other patches for + this branch, so Node.js can effectively bump the patch version. + * In some cases the patch may require extra effort to merge in case V8 has + changed substantially. For important issues we may be able to lean on the + V8 team to get help with reimplementing the patch. + * Run the Node.js [V8-CI](https://ci.nodejs.org/job/node-test-commit-v8-linux/) + in addition to the [Node.js CI](https://ci.nodejs.org/job/node-test-pull-request/). An example for workflow how to cherry-pick consider the bug [RegExp show inconsistent result with other browsers](https://crbug.com/v8/5199). @@ -191,8 +230,18 @@ From the bug we can see that it was merged by V8 into 5.2 and 5.3, and not into V8 5.1 (since it was already abandoned). Since Node.js `v6.x` uses V8 5.1, the fix needed to be cherry-picked. To cherry-pick, here's an example workflow: -* Download and apply the commit linked-to in the issue (in this case a51f429). `curl -L https://github.com/v8/v8/commit/a51f429.patch | git am -3 --directory=deps/v8`. If the branches have diverged significantly, this may not apply cleanly. It may help to try to cherry-pick the merge to the oldest branch that was done upstream in V8. In this example, this would be the patch from the merge to 5.2. The hope is that this would be closer to the V8 5.1, and has a better chance of applying cleanly. If you're stuck, feel free to ping @ofrobots for help. -* Modify the commit message to match the format we use for V8 backports and replace yourself as the author. `git commit --amend --reset-author`. You may want to add extra description if necessary to indicate the impact of the fix on Node.js. In this case the original issue was descriptive enough. Example: +* Download and apply the commit linked-to in the issue (in this case a51f429). +`curl -L https://github.com/v8/v8/commit/a51f429.patch | git am -3 +--directory=deps/v8`. If the branches have diverged significantly, this may not +apply cleanly. It may help to try to cherry-pick the merge to the oldest branch +that was done upstream in V8. In this example, this would be the patch from the +merge to 5.2. The hope is that this would be closer to the V8 5.1, and has a +better chance of applying cleanly. If you're stuck, feel free to ping @ofrobots +for help. +* Modify the commit message to match the format we use for V8 backports and +replace yourself as the author. `git commit --amend --reset-author`. You may +want to add extra description if necessary to indicate the impact of the fix on +Node.js. In this case the original issue was descriptive enough. Example: ```console deps: cherry-pick a51f429 from V8 upstream @@ -213,7 +262,10 @@ Original commit message: Refs: https://github.com/v8/v8/commit/a51f429772d1e796744244128c9feeab4c26a854 PR-URL: https://github.com/nodejs/node/pull/7833 ``` -* Open a PR against the `v6.x-staging` branch in the Node.js repo. Launch the normal and [V8-CI](https://ci.nodejs.org/job/node-test-commit-v8-linux/) using the Node.js CI system. We only needed to backport to `v6.x` as the other LTS branches weren't affected by this bug. +* Open a PR against the `v6.x-staging` branch in the Node.js repo. Launch the +normal and [V8-CI](https://ci.nodejs.org/job/node-test-commit-v8-linux/) using +the Node.js CI system. We only needed to backport to `v6.x` as the other LTS +branches weren't affected by this bug. ### Backports Identified by the V8 team @@ -277,9 +329,14 @@ upstream, that is, whenever a new release of Chrome comes out. Upgrading major versions would be much harder to do with the patch mechanism above. A better strategy is to -1. Audit the current master branch and look at the patches that have been floated since the last major V8 update. -1. Replace the copy of V8 in Node.js with a fresh checkout of the latest stable V8 branch. Special care must be taken to recursively update the DEPS that V8 has a compile time dependency on (at the moment of this writing, these are only trace_event and gtest_prod.h) -1. Refloat (cherry-pick) all the patches from list computed in 1) as necessary. Some of the patches may no longer be necessary. +1. Audit the current master branch and look at the patches that have been +floated since the last major V8 update. +1. Replace the copy of V8 in Node.js with a fresh checkout of the latest stable +V8 branch. Special care must be taken to recursively update the DEPS that V8 +has a compile time dependency on (at the moment of this writing, these are only +trace_event and gtest_prod.h) +1. Refloat (cherry-pick) all the patches from list computed in 1) as necessary. +Some of the patches may no longer be necessary. To audit for floating patches: @@ -287,7 +344,10 @@ To audit for floating patches: git log --oneline deps/v8 ``` -To replace the copy of V8 in Node.js, use the `[update-v8](https://gist.github.com/targos/8da405e96e98fdff01a395bed365b816)` script2. For example, if you want to replace the copy of V8 in Node.js with the branch-head for V8 5.1 branch: +To replace the copy of V8 in Node.js, use the +`[update-v8](https://gist.github.com/targos/8da405e96e98fdff01a395bed365b816)` +script2. For example, if you want to replace the copy of V8 in +Node.js with the branch-head for V8 5.1 branch: ```shell cd $NODE_DIR @@ -309,15 +369,19 @@ branches. This has several benefits: * The process to update the version of V8 in Node.js could be automated to track the tips of various V8 branches in `nodejs/v8`. -* It would simplify cherry-picking and porting of fixes between branches as the version bumps in `v8-version.h` would happen as part of this update instead of on every change. +* It would simplify cherry-picking and porting of fixes between branches as the + version bumps in `v8-version.h` would happen as part of this update instead + of on every change. * It would simplify the V8-CI and make it more automatable. * The history of the V8 branch in `nodejs/v8` becomes purer and it would make it easier to pull in the V8 team for help with reviewing. -* It would make it simpler to setup an automated build that tracks Node.js master + V8 lkgr integration build. +* It would make it simpler to setup an automated build that tracks Node.js + master + V8 lkgr integration build. This would require some tooling to: -* A script that would update the V8 in a specific Node.js branch with V8 from upstream (dependent on branch abandoned vs. active). +* A script that would update the V8 in a specific Node.js branch with V8 from + upstream (dependent on branch abandoned vs. active). * We need a script to bump V8 version numbers when a new version of V8 is promoted from `nodejs/v8` to `nodejs/node`. * Enabled the V8-CI build in Jenkins to build from the `nodejs/v8` fork. @@ -343,6 +407,7 @@ up working, we will investigate making this change upstream. ### Notes -1Node.js 0.12 and older are intentionally omitted from this document as their support is ending soon. +1Node.js 0.12 and older are intentionally omitted from this document +as their support is ending soon. 2@targos is working on [a port of this script](https://github.com/targos/update-v8). diff --git a/doc/guides/maintaining-npm.md b/doc/guides/maintaining-npm.md index af9d3af04f2360..08621b115b3ba1 100644 --- a/doc/guides/maintaining-npm.md +++ b/doc/guides/maintaining-npm.md @@ -21,7 +21,9 @@ $ git checkout vX.Y.Z $ make release ``` -Note: please run `npm dist-tag ls npm` and make sure this is the `latest` **dist-tag**. `latest` on git is usually released as `next` when it's time to downstream +Note: please run `npm dist-tag ls npm` and make sure this is the `latest` +**dist-tag**. `latest` on git is usually released as `next` when it's time to +downstream ## Step 3: Remove old npm diff --git a/doc/guides/writing-and-running-benchmarks.md b/doc/guides/writing-and-running-benchmarks.md index 75435daf394898..43facbd3a96da7 100644 --- a/doc/guides/writing-and-running-benchmarks.md +++ b/doc/guides/writing-and-running-benchmarks.md @@ -31,8 +31,8 @@ either [`wrk`][wrk] or [`autocannon`][autocannon]. path. In order to compare two HTTP benchmark runs, make sure that the Node.js version in the path is not altered. -`wrk` may be available through one of the available package managers. If not, it can -be easily built [from source][wrk] via `make`. +`wrk` may be available through one of the available package managers. If not, +it can be easily built [from source][wrk] via `make`. By default, `wrk` will be used as the benchmarker. If it is not available, `autocannon` will be used in its place. When creating an HTTP benchmark, the @@ -222,9 +222,9 @@ is less than `0.05`._ The `compare.R` tool can also produce a box plot by using the `--plot filename` option. In this case there are 48 different benchmark combinations, and there may be a need to filter the csv file. This can be done while benchmarking -using the `--set` parameter (e.g. `--set encoding=ascii`) or by filtering results -afterwards using tools such as `sed` or `grep`. In the `sed` case be sure to -keep the first line since that contains the header information. +using the `--set` parameter (e.g. `--set encoding=ascii`) or by filtering +results afterwards using tools such as `sed` or `grep`. In the `sed` case be +sure to keep the first line since that contains the header information. ```console $ cat compare-pr-5134.csv | sed '1p;/encoding=ascii/!d' | Rscript benchmark/compare.R --plot compare-plot.png diff --git a/doc/guides/writing-tests.md b/doc/guides/writing-tests.md index ec9398dcb928ec..4607eb5f752b70 100644 --- a/doc/guides/writing-tests.md +++ b/doc/guides/writing-tests.md @@ -138,15 +138,15 @@ platforms. ### The *common* API -Make use of the helpers from the `common` module as much as possible. Please refer -to the [common file documentation](https://github.com/nodejs/node/tree/master/test/common) +Make use of the helpers from the `common` module as much as possible. Please +refer to the [common file documentation](https://github.com/nodejs/node/tree/master/test/common) for the full details of the helpers. #### common.mustCall -One interesting case is `common.mustCall`. The use of `common.mustCall` may avoid -the use of extra variables and the corresponding assertions. Let's explain this -with a real test from the test suite. +One interesting case is `common.mustCall`. The use of `common.mustCall` may +avoid the use of extra variables and the corresponding assertions. Let's +explain this with a real test from the test suite. ```javascript 'use strict'; @@ -200,9 +200,11 @@ const server = http.createServer(common.mustCall(function(req, res) { ``` #### Countdown Module -The common [Countdown module](https://github.com/nodejs/node/tree/master/test/common#countdown-module) provides a simple countdown mechanism for tests that +The common [Countdown module](https://github.com/nodejs/node/tree/master/test/common#countdown-module) +provides a simple countdown mechanism for tests that require a particular action to be taken after a given number of completed tasks -(for instance, shutting down an HTTP server after a specific number of requests). +(for instance, shutting down an HTTP server after a specific number of +requests). ```javascript const Countdown = require('../common/countdown'); diff --git a/tools/icu/README.md b/tools/icu/README.md index 2b5d74ac205fb6..991dd3e0e866d7 100644 --- a/tools/icu/README.md +++ b/tools/icu/README.md @@ -2,8 +2,10 @@ ## How to upgrade ICU -- Make sure your node workspace is clean (clean `git status`) should be sufficient. -- Configure Node with the specific [ICU version](http://icu-project.org/download) you want to upgrade to, for example: +- Make sure your node workspace is clean (clean `git status`) should be + sufficient. +- Configure Node with the specific [ICU version](http://icu-project.org/download) + you want to upgrade to, for example: ```shell ./configure \ @@ -12,11 +14,11 @@ make ``` -(The equivalent `vcbuild.bat` commands should work also. Note that we use the `.tgz` and not the `.zip` here, -that is because of line endings.) +(The equivalent `vcbuild.bat` commands should work also. Note that we use the +`.tgz` and not the `.zip` here, that is because of line endings.) -- (note- may need to make changes in `icu-generic.gyp` or `tools/icu/patches` for -version specific stuff) +- (note- may need to make changes in `icu-generic.gyp` or `tools/icu/patches` +for version specific stuff) - Verify the node build works diff --git a/tools/remark-preset-lint-node/index.js b/tools/remark-preset-lint-node/index.js index 132bc7eae24210..95514e7dbe9b21 100644 --- a/tools/remark-preset-lint-node/index.js +++ b/tools/remark-preset-lint-node/index.js @@ -40,5 +40,6 @@ module.exports.plugins = [ [require('remark-lint-first-heading-level'), 1], [require('remark-lint-heading-style'), 'atx'], [require('remark-lint-strong-marker'), '*'], - [require('remark-lint-table-cell-padding'), 'padded'] + [require('remark-lint-table-cell-padding'), 'padded'], + [require('remark-lint-maximum-line-length'), 80] ]; diff --git a/tools/remark-preset-lint-node/package.json b/tools/remark-preset-lint-node/package.json index 000a5a2901d4e7..33c5882f97b81a 100644 --- a/tools/remark-preset-lint-node/package.json +++ b/tools/remark-preset-lint-node/package.json @@ -19,6 +19,7 @@ "remark-lint-first-heading-level": "^1.0.0", "remark-lint-hard-break-spaces": "^1.0.1", "remark-lint-heading-style": "^1.0.0", + "remark-lint-maximum-line-length": "^1.0.2", "remark-lint-no-auto-link-without-protocol": "^1.0.0", "remark-lint-no-blockquote-without-caret": "^1.0.0", "remark-lint-no-duplicate-definitions": "^1.0.0",