diff --git a/BUILDING.md b/BUILDING.md index 74b5903ed22cd0..a992688d3a8808 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -62,7 +62,7 @@ note1 - The gcc4.8-libs package needs to be installed, because node *Note*: On Windows, running Node.js in windows terminal emulators like `mintty` requires the usage of [winpty](https://github.com/rprichard/winpty) for - Node's tty channels to work correctly (e.g. `winpty node.exe script.js`). + Node's tty channels to work correctly (for example: `winpty node.exe script.js`). In "Git bash" if you call the node shell alias (`node` without the `.exe` extension), `winpty` is used automatically. @@ -251,7 +251,7 @@ To test if Node.js was built correctly: > Release\node -e "console.log('Hello from Node.js', process.version)" ``` -### Android/Android-based devices (e.g. Firefox OS) +### Android/Android-based devices (for example: Firefox OS) Although these instructions for building on Android are provided, please note that Android is not an officially supported platform at this time. Patches to diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 5a1d51dafe375c..f74df3341608de 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -243,7 +243,7 @@ Examples of breaking changes include: * altering expected timing of an event * changing the side effects of using a particular API -Purely additive changes (e.g. adding new events to `EventEmitter` +Purely additive changes (for example: adding new events to `EventEmitter` implementations, adding new arguments to a method in a way that allows existing code to continue working without modification, or adding new properties to an options argument) are semver-minor changes. @@ -267,7 +267,7 @@ Such changes *must* be handled as semver-major changes but MAY be landed without a [Deprecation cycle](#deprecation-cycle). Note that errors thrown, along with behaviors and APIs implemented by -dependencies of Node.js (e.g. those originating from V8) are generally not +dependencies of Node.js (for example: those originating from V8) are generally not under the control of Node.js and therefore *are not directly subject to this policy*. However, care should still be taken when landing updates to dependencies when it is known or expected that breaking changes to error @@ -308,7 +308,7 @@ Specifically: * Breaking changes should *never* land in Current or LTS except when: * Resolving critical security issues. - * Fixing a critical bug (e.g. fixing a memory leak) requires a breaking + * Fixing a critical bug (for example: fixing a memory leak) requires a breaking change. * There is TSC consensus that the change is required. * If a breaking commit does accidentally land in a Current or LTS branch, an @@ -623,7 +623,7 @@ error: failed to push some refs to 'https://github.com/nodejs/node' hint: Updates were rejected because the remote contains work that you do hint: not have locally. This is usually caused by another repository pushing hint: to the same ref. You may want to first integrate the remote changes -hint: (e.g. 'git pull ...') before pushing again. +hint: (for example: 'git pull ...') before pushing again. hint: See the 'Note about fast-forwards' in 'git push --help' for details. ``` diff --git a/CPP_STYLE_GUIDE.md b/CPP_STYLE_GUIDE.md index 5a275094ad16fa..c112359692185c 100644 --- a/CPP_STYLE_GUIDE.md +++ b/CPP_STYLE_GUIDE.md @@ -168,7 +168,7 @@ What it says in the title. ## Ownership and Smart Pointers -"Smart" pointers are classes that act like pointers, e.g. +_Smart pointers_ are classes that act like pointers, such as by overloading the `*` and `->` operators. Some smart pointer types can be used to automate ownership bookkeeping, to ensure these responsibilities are met. `std::unique_ptr` is a smart pointer type introduced in C++11, which diff --git a/doc/STYLE_GUIDE.md b/doc/STYLE_GUIDE.md index 7fc2d6e0b1bb13..2de329970c50b3 100644 --- a/doc/STYLE_GUIDE.md +++ b/doc/STYLE_GUIDE.md @@ -3,7 +3,7 @@ * Documentation is written in markdown files with names formatted as `lowercase-with-dashes.md`. * Underscores in filenames are allowed only when they are present in the - topic the document will describe (e.g. `child_process`). + topic the document will describe (for example: `child_process`). * Some files, such as top-level markdown files, are exceptions. * Documents should be word-wrapped at 80 characters. * The formatting described in `.editorconfig` is preferred. diff --git a/doc/api/addons.md b/doc/api/addons.md index c6802530f6dc67..82a8aacca19d35 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -170,7 +170,7 @@ try { Node.js uses a number of statically linked libraries such as V8, libuv and OpenSSL. All Addons are required to link to V8 and may link to any of the other dependencies as well. Typically, this is as simple as including -the appropriate `#include <...>` statements (e.g. `#include `) and +the appropriate `#include <...>` statements (for example: `#include `) and `node-gyp` will locate the appropriate headers automatically. However, there are a few caveats to be aware of: @@ -221,7 +221,7 @@ illustration of how it can be used. > Stability: 1 - Experimental N-API is an API for building native Addons. It is independent from -the underlying JavaScript runtime (e.g. V8) and is maintained as part of +the underlying JavaScript runtime (for example: V8) and is maintained as part of Node.js itself. This API will be Application Binary Interface (ABI) stable across version of Node.js. It is intended to insulate Addons from changes in the underlying JavaScript engine and allow modules diff --git a/doc/api/assert.md b/doc/api/assert.md index 04f312aa6634fa..d52f735ec45e1d 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -74,7 +74,7 @@ Please note that this will also deactivate the colors in the REPL. When accessing `assert` directly instead of using the `strict` property, the [Abstract Equality Comparison][] will be used for any function without a -"strict" in its name (e.g. [`assert.deepEqual()`][]). +"strict" in its name (for example: [`assert.deepEqual()`][]). It can be accessed using: @@ -727,7 +727,7 @@ assert.ok(typeof 123 === 'string'); // throws: // "AssertionError: false == true -// In a file (e.g. test.js): +// In a file (for example: test.js): assert.ok(typeof 123 === 'string'); // throws: // "AssertionError: The expression evaluated to a falsy value: diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 4fa23f28d116b0..011fb12e4e30f1 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -59,8 +59,8 @@ asyncHook.disable(); function init(asyncId, type, triggerAsyncId, resource) { } // before is called just before the resource's callback is called. It can be -// called 0-N times for handles (e.g. TCPWrap), and will be called exactly 1 -// time for requests (e.g. FSReqWrap). +// called 0-N times for handles (for example: TCPWrap), and will be called exactly 1 +// time for requests (for example: FSReqWrap). function before(asyncId) { } // after is called just after the resource's callback has finished. diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 5e72e3bd969b4f..ca1ed8ab8fcd97 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -53,7 +53,7 @@ In versions of Node.js prior to v6, `Buffer` instances were created using the `Buffer` constructor function, which allocates the returned `Buffer` differently based on what arguments are provided: -* Passing a number as the first argument to `Buffer()` (e.g. `new Buffer(10)`), +* Passing a number as the first argument to `Buffer()` (for example: `new Buffer(10)`), allocates a new `Buffer` object of the specified size. Prior to Node.js 8.0.0, the memory allocated for such `Buffer` instances is *not* initialized and *can contain sensitive data*. Such `Buffer` instances *must* be subsequently @@ -703,7 +703,7 @@ Returns the actual byte length of a string. This is not the same as a string. *Note*: For `'base64'` and `'hex'`, this function assumes valid input. For -strings that contain non-Base64/Hex-encoded data (e.g. whitespace), the return +strings that contain non-Base64/Hex-encoded data (for example: whitespace), the return value might be greater than the length of a `Buffer` created from the string. Example: diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 50b5be5473d5f4..175a7a5c8bb010 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -971,7 +971,7 @@ The `'disconnect'` event will be emitted when there are no messages in the process of being received. This will most often be triggered immediately after calling `subprocess.disconnect()`. -Note that when the child process is a Node.js instance (e.g. spawned using +Note that when the child process is a Node.js instance (for example: spawned using [`child_process.fork()`]), the `process.disconnect()` method can be invoked within the child process to close the IPC channel as well. diff --git a/doc/api/cluster.md b/doc/api/cluster.md index 6ef451cb9af714..7f2ca189831e80 100644 --- a/doc/api/cluster.md +++ b/doc/api/cluster.md @@ -149,7 +149,7 @@ added: v0.11.2 --> * `code` {number} The exit code, if it exited normally. -* `signal` {string} The name of the signal (e.g. `'SIGHUP'`) that caused +* `signal` {string} The name of the signal (for example: `'SIGHUP'`) that caused the process to be killed. Similar to the `cluster.on('exit')` event, but specific to this worker. @@ -482,7 +482,7 @@ added: v0.7.9 * `worker` {cluster.Worker} * `code` {number} The exit code, if it exited normally. -* `signal` {string} The name of the signal (e.g. `'SIGHUP'`) that caused +* `signal` {string} The name of the signal (for example: `'SIGHUP'`) that caused the process to be killed. When any of the workers die the cluster module will emit the `'exit'` event. diff --git a/doc/api/console.md b/doc/api/console.md index 76f6c6ac4623a7..343f8edc7701e9 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -272,7 +272,7 @@ console.error('error', code); // Prints: error 5, to stderr ``` -If formatting elements (e.g. `%d`) are not found in the first string then +If formatting elements (for example: `%d`) are not found in the first string then [`util.inspect()`][] is called on each argument and the resulting string values are concatenated. See [`util.format()`][] for more information. diff --git a/doc/api/crypto.md b/doc/api/crypto.md index b9f3b95c0a9c96..5fc58df6665454 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -1264,7 +1264,7 @@ In line with OpenSSL's recommendation to use PBKDF2 instead of [`EVP_BytesToKey`][] it is recommended that developers derive a key and IV on their own using [`crypto.pbkdf2()`][] and to use [`crypto.createCipheriv()`][] to create the `Cipher` object. Users should not use ciphers with counter mode -(e.g. CTR, GCM, or CCM) in `crypto.createCipher()`. A warning is emitted when +(for example: CTR, GCM, or CCM) in `crypto.createCipher()`. A warning is emitted when they are used in order to avoid the risk of IV reuse that causes vulnerabilities. For the case when IV is reused in GCM, see [Nonce-Disrespecting Adversaries][] for details. @@ -2015,7 +2015,7 @@ The Crypto module was added to Node.js before there was the concept of a unified Stream API, and before there were [`Buffer`][] objects for handling binary data. As such, the many of the `crypto` defined classes have methods not typically found on other Node.js classes that implement the [streams][stream] -API (e.g. `update()`, `final()`, or `digest()`). Also, many methods accepted +API (for example: `update()`, `final()`, or `digest()`). Also, many methods accepted and returned `'latin1'` encoded strings by default rather than Buffers. This default was changed after Node.js v0.8 to use [`Buffer`][] objects by default instead. diff --git a/doc/api/debugger.md b/doc/api/debugger.md index b0da263f5947b4..3dbf1f6109df02 100644 --- a/doc/api/debugger.md +++ b/doc/api/debugger.md @@ -176,8 +176,7 @@ V8 Inspector integration allows attaching Chrome DevTools to Node.js 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, -e.g. `--inspect=9222` will accept DevTools connections on port 9222. +Node.js application. It is also possible to supply a custom port with that flag (for example: `--inspect=9222` will accept DevTools connections on port 9222). To break on the first line of the application code, pass the `--inspect-brk` flag instead of `--inspect`. diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index e38c29949c4ced..01cd15ea19744c 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -570,7 +570,7 @@ Type: Documentation-only The `http` module `outgoingMessage._headers` and `outgoingMessage._headerNames` properties have been deprecated. Please instead use one of the public methods -(e.g. `outgoingMessage.getHeader()`, `outgoingMessage.getHeaders()`, +(for example: `outgoingMessage.getHeader()`, `outgoingMessage.getHeaders()`, `outgoingMessage.getHeaderNames()`, `outgoingMessage.hasHeader()`, `outgoingMessage.removeHeader()`, `outgoingMessage.setHeader()`) for working with outgoing headers. diff --git a/doc/api/dgram.md b/doc/api/dgram.md index e44bf3eea5a166..f3b457a4ff406f 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -128,7 +128,7 @@ useful. A bound datagram socket keeps the Node.js process running to receive datagram messages. -If binding fails, an `'error'` event is generated. In rare case (e.g. +If binding fails, an `'error'` event is generated. In rare case (for example: attempting to bind with a closed socket), an [`Error`][] may be thrown. Example of a UDP server listening on port 41234: @@ -189,7 +189,7 @@ port sharing results in an error. A bound datagram socket keeps the Node.js process running to receive datagram messages. -If binding fails, an `'error'` event is generated. In rare case (e.g. +If binding fails, an `'error'` event is generated. In rare case (for example: attempting to bind with a closed socket), an [`Error`][] may be thrown. An example socket listening on an exclusive port is shown below. diff --git a/doc/api/dns.md b/doc/api/dns.md index c1ec1cfa51c41c..a59aea57d6b556 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -27,7 +27,7 @@ dns.lookup('iana.org', (err, address, family) => { and that _always_ use the network to perform DNS queries. This category contains all functions in the `dns` module _except_ [`dns.lookup()`][]. These functions do not use the same set of configuration files used by -[`dns.lookup()`][] (e.g. `/etc/hosts`). These functions should be used by +[`dns.lookup()`][] (for example: `/etc/hosts`). These functions should be used by developers who do not want to use the underlying operating system's facilities for name resolution, and instead want to _always_ perform DNS queries. @@ -153,7 +153,7 @@ changes: - `address` {string} A string representation of an IPv4 or IPv6 address. - `family` {integer} `4` or `6`, denoting the family of `address`. -Resolves a hostname (e.g. `'nodejs.org'`) into the first found A (IPv4) or +Resolves a hostname (for example: `'nodejs.org'`) into the first found A (IPv4) or AAAA (IPv6) record. All `option` properties are optional. If `options` is an integer, then it must be `4` or `6` – if `options` is not provided, then IPv4 and IPv6 addresses are both returned if found. @@ -217,8 +217,8 @@ added: v0.11.14 - `port` {number} - `callback` {Function} - `err` {Error} - - `hostname` {string} e.g. `example.com` - - `service` {string} e.g. `http` + - `hostname` {string} for example: `example.com` + - `service` {string} for example: `http` Resolves the given `address` and `port` into a hostname and service using the operating system's underlying `getnameinfo` implementation. @@ -250,7 +250,7 @@ added: v0.1.27 - `err` {Error} - `records` {string[] | Object[] | Object} -Uses the DNS protocol to resolve a hostname (e.g. `'nodejs.org'`) into an array +Uses the DNS protocol to resolve a hostname (for example: `'nodejs.org'`) into an array of the resource records. The `callback` function has arguments `(err, records)`. When successful, `records` will be an array of resource records. The type and structure of individual results varies based on `rrtype`: @@ -293,7 +293,7 @@ changes: Uses the DNS protocol to resolve a IPv4 addresses (`A` records) for the `hostname`. The `addresses` argument passed to the `callback` function -will contain an array of IPv4 addresses (e.g. +will contain an array of IPv4 addresses (for example: `['74.125.79.104', '74.125.79.105', '74.125.79.106']`). @@ -333,7 +333,7 @@ added: v0.3.2 Uses the DNS protocol to resolve `CNAME` records for the `hostname`. The `addresses` argument passed to the `callback` function will contain an array of canonical name records available for the `hostname` -(e.g. `['bar.example.com']`). +(for example: `['bar.example.com']`). ## dns.resolveMx(hostname, callback) -* `hostname` {string} A SNI hostname or wildcard (e.g. `'*'`) +* `hostname` {string} A SNI hostname or wildcard (for example: `'*'`) * `context` {Object} An object containing any of the possible properties - from the [`tls.createSecureContext()`][] `options` arguments (e.g. `key`, + from the [`tls.createSecureContext()`][] `options` arguments (for example: `key`, `cert`, `ca`, etc). The `server.addContext()` method adds a secure context that will be used if @@ -442,7 +442,7 @@ encryption of written data and all required TLS negotiation. Instances of `tls.TLSSocket` implement the duplex [Stream][] interface. -*Note*: Methods that return TLS connection metadata (e.g. +*Note*: Methods that return TLS connection metadata (for example: [`tls.TLSSocket.getPeerCertificate()`][] will only return data while the connection is open. @@ -521,7 +521,7 @@ added: v0.11.4 Returns the bound address, the address family name, and port of the underlying socket as reported by the operating system. Returns an -object with three properties, e.g. +object with three properties, for example: `{ port: 12346, family: 'IPv4', address: '127.0.0.1' }` ### tlsSocket.authorizationError @@ -834,15 +834,15 @@ changes: * `NPNProtocols` {string[]|Buffer[]|Uint8Array[]|Buffer|Uint8Array} An array of strings, `Buffer`s or `Uint8Array`s, or a single `Buffer` or `Uint8Array` containing supported NPN protocols. `Buffer`s should have the - format `[len][name][len][name]...` e.g. `0x05hello0x05world`, where the + format `[len][name][len][name]...` for example: `0x05hello0x05world`, where the first byte is the length of the next protocol name. Passing an array is - usually much simpler, e.g. `['hello', 'world']`. + usually much simpler, for example: `['hello', 'world']`. * `ALPNProtocols`: {string[]|Buffer[]|Uint8Array[]|Buffer|Uint8Array} An array of strings, `Buffer`s or `Uint8Array`s, or a single `Buffer` or `Uint8Array` containing the supported ALPN protocols. `Buffer`s should have - the format `[len][name][len][name]...` e.g. `0x05hello0x05world`, where the + the format `[len][name][len][name]...` for example: `0x05hello0x05world`, where the first byte is the length of the next protocol name. Passing an array is - usually much simpler, e.g. `['hello', 'world']`. + usually much simpler, for example: `['hello', 'world']`. * `servername`: {string} Server name for the SNI (Server Name Indication) TLS extension. * `checkServerIdentity(servername, cert)` {Function} A callback function @@ -1104,16 +1104,16 @@ changes: * `NPNProtocols` {string[]|Buffer[]|Uint8Array[]|Buffer|Uint8Array} An array of strings, `Buffer`s or `Uint8Array`s, or a single `Buffer` or `Uint8Array` containing supported NPN protocols. `Buffer`s should have the - format `[len][name][len][name]...` e.g. `0x05hello0x05world`, where the + format `[len][name][len][name]...` for example: `0x05hello0x05world`, where the first byte is the length of the next protocol name. Passing an array is - usually much simpler, e.g. `['hello', 'world']`. + usually much simpler, for example: `['hello', 'world']`. (Protocols should be ordered by their priority.) * `ALPNProtocols`: {string[]|Buffer[]|Uint8Array[]|Buffer|Uint8Array} An array of strings, `Buffer`s or `Uint8Array`s, or a single `Buffer` or `Uint8Array` containing the supported ALPN protocols. `Buffer`s should have - the format `[len][name][len][name]...` e.g. `0x05hello0x05world`, where the + the format `[len][name][len][name]...` for example: `0x05hello0x05world`, where the first byte is the length of the next protocol name. Passing an array is - usually much simpler, e.g. `['hello', 'world']`. + usually much simpler, for example: `['hello', 'world']`. (Protocols should be ordered by their priority.) When the server receives both NPN and ALPN extensions from the client, ALPN takes precedence over NPN and the server does not send an NPN diff --git a/doc/api/url.md b/doc/api/url.md index 5f504a5bc8937f..05a79d64f04bba 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -87,7 +87,7 @@ Standard. [Examples of parsed URLs][] may be found in the Standard itself. *Note*: In accordance with browser conventions, all properties of `URL` objects are implemented as getters and setters on the class prototype, rather than as data properties on the object itself. Thus, unlike [legacy urlObject][]s, using -the `delete` keyword on any properties of `URL` objects (e.g. `delete +the `delete` keyword on any properties of `URL` objects (for example: `delete myURL.protocol`, `delete myURL.pathname`, etc) has no effect but will still return `true`. diff --git a/doc/api/util.md b/doc/api/util.md index c9ce952af3885f..2a5680c5ab0f2b 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -497,7 +497,7 @@ console.log(util.inspect(o, { compact: false, breakLength: 80 })); // } // } -// Setting `breakLength` to e.g. 150 will print the "Lorem ipsum" text in a +// Setting `breakLength` to for example: 150 will print the "Lorem ipsum" text in a // single line. // Reducing the `breakLength` will split the "Lorem ipsum" text in smaller // chunks. diff --git a/doc/api/vm.md b/doc/api/vm.md index 3ac70091e58552..2d158c6a8e39fa 100644 --- a/doc/api/vm.md +++ b/doc/api/vm.md @@ -456,7 +456,7 @@ console.log('localVar:', localVar); Because `vm.runInThisContext()` does not have access to the local scope, `localVar` is unchanged. In contrast, [`eval()`][] *does* have access to the local scope, so the value `localVar` is changed. In this way -`vm.runInThisContext()` is much like an [indirect `eval()` call][], e.g. +`vm.runInThisContext()` is much like an [indirect `eval()` call][], for example: `(0,eval)('code')`. ## Example: Running an HTTP Server within a VM @@ -489,7 +489,7 @@ vm.runInThisContext(code)(require); ``` *Note*: The `require()` in the above case shares the state with the context it -is passed from. This may introduce risks when untrusted code is executed, e.g. +is passed from. This may introduce risks when untrusted code is executed, for example: altering objects in the context in unwanted ways. ## What does it mean to "contextify" an object? diff --git a/doc/api/zlib.md b/doc/api/zlib.md index 909a52d6e54ef0..43b88c72a063e9 100644 --- a/doc/api/zlib.md +++ b/doc/api/zlib.md @@ -146,7 +146,7 @@ zlib.unzip( }); ``` -This will not change the behavior in other error-throwing situations, e.g. +This will not change the behavior in other error-throwing situations, for example: when the input data has an invalid format. Using this method, it will not be possible to determine whether the input ended prematurely or lacks the integrity checks, making it necessary to manually check that the diff --git a/doc/guides/contributing/pull-requests.md b/doc/guides/contributing/pull-requests.md index 5812c8c54645e2..27dd3d650ca75f 100644 --- a/doc/guides/contributing/pull-requests.md +++ b/doc/guides/contributing/pull-requests.md @@ -475,7 +475,7 @@ avoid stalling the Pull Request. Most nits can typically be fixed by the Node.js Collaborator landing the Pull Request but they can also be an opportunity for the contributor to learn a bit more about the project. -It is always good to clearly indicate nits when you comment: e.g. +It is always good to clearly indicate nits when you comment: for example: `Nit: change foo() to bar(). But this is not blocking.` ### Be aware of the person behind the code diff --git a/doc/guides/maintaining-V8.md b/doc/guides/maintaining-V8.md index 04bc155660105b..f92ffbc453afa3 100644 --- a/doc/guides/maintaining-V8.md +++ b/doc/guides/maintaining-V8.md @@ -193,7 +193,7 @@ backport the fix: * 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, + that still contain the bug. (for example: 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 @@ -214,7 +214,7 @@ 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: - * Checkout a branch off the appropriate *vY.x-staging* branch (e.g. + * Checkout a branch off the appropriate *vY.x-staging* branch (for example: *v6.x-staging* to fix an issue in V8 5.1). * Cherry-pick the commit(s) from the V8 repository. * On Node.js < 9.0.0: Increase the patch level version in `v8-version.h`. diff --git a/doc/guides/writing-and-running-benchmarks.md b/doc/guides/writing-and-running-benchmarks.md index 22e235df323d52..5dda3ceff4f540 100644 --- a/doc/guides/writing-and-running-benchmarks.md +++ b/doc/guides/writing-and-running-benchmarks.md @@ -223,7 +223,7 @@ 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 +using the `--set` parameter (for example: `--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. @@ -285,7 +285,7 @@ chunk encoding mean confidence.interval Because the scatter plot can only show two variables (in this case _chunk_ and _encoding_) the rest is aggregated. Sometimes aggregating is a problem, this can be solved by filtering. This can be done while benchmarking using the -`--set` parameter (e.g. `--set encoding=ascii`) or by filtering results +`--set` parameter (for example: `--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. diff --git a/doc/releases.md b/doc/releases.md index 18126b713b1d85..83402d8cfc62f7 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -126,10 +126,10 @@ be produced with a version string that does not have a trailing pre-release tag: This macro is used to signal an ABI version for native addons. It currently has two common uses in the community: -- Determining what API to work against for compiling native addons, e.g. +- Determining what API to work against for compiling native addons, for example: [NAN](https://github.com/nodejs/nan) uses it to form a compatibility-layer for much of what it wraps. -- Determining the ABI for downloading pre-built binaries of native addons, e.g. +- Determining the ABI for downloading pre-built binaries of native addons, for example: [node-pre-gyp](https://github.com/mapbox/node-pre-gyp) uses this value as exposed via `process.versions.modules` to help determine the appropriate binary to download at install-time. @@ -167,7 +167,7 @@ $ changelog-maker --group --start-ref v2.3.1 There is a separate `CHANGELOG_*.md` file for each major Node.js release line. These are located in the `doc/changelogs/` directory. Once the formatted list of changes is collected, it must be added to the top of the relevant changelog file -in the release branch (e.g. a release for Node.js v4 would be added to the +in the release branch (for example: a release for Node.js v4 would be added to the `/doc/changelogs/CHANGELOG_V4.md`). **Please do *not* add the changelog entries to the root `CHANGELOG.md` file.** @@ -221,7 +221,7 @@ doc/api/*.md`. If this release includes any new deprecations it is necessary to ensure that those are assigned a proper static deprecation code. These are listed in the docs (see `doc/api/deprecations.md`) and in the source as `DEP00XX`. The code -must be assigned a number (e.g. `DEP0012`). Note that this assignment should +must be assigned a number (for example: `DEP0012`). Note that this assignment should occur when the PR is landed, but a check will be made when the release built is run. @@ -390,7 +390,7 @@ This sets up the branch so that nightly builds are produced with the next version number _and_ a pre-release tag. Merge your release proposal branch into the stable branch that you are releasing -from (e.g. `v8.x`), and rebase the corresponding staging branch (`v8.x-staging`) +from (for example: `v8.x`), and rebase the corresponding staging branch (`v8.x-staging`) on top of that. Cherry-pick the release commit to `master`. After cherry-picking, edit