diff options
author | Alexey Orlenko <eaglexrlnk@gmail.com> | 2017-05-20 23:15:58 +0300 |
---|---|---|
committer | Refael Ackermann <refack@gmail.com> | 2017-05-26 01:49:41 +0300 |
commit | 2af49b6c89dd4355ec0c1779fdb1fb12cf10e68d (patch) | |
tree | d0ba4f62fff9db7d42b3f86c7358d9219b288698 | |
parent | b3d1e3d4c720729c8f14e413a285660547ee677a (diff) |
doc: make the style of notes consistent
Make the style of "Note:" paragraphs consistent and document the
guidelines in `doc/STYLE_GUIDE.md`.
PR-URL: https://github.com/nodejs/node/pull/13133
Fixes: https://github.com/nodejs/node/issues/13131
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
-rw-r--r-- | doc/STYLE_GUIDE.md | 4 | ||||
-rw-r--r-- | doc/api/addons.md | 4 | ||||
-rw-r--r-- | doc/api/buffer.md | 16 | ||||
-rw-r--r-- | doc/api/child_process.md | 46 | ||||
-rw-r--r-- | doc/api/cli.md | 10 | ||||
-rw-r--r-- | doc/api/console.md | 8 | ||||
-rw-r--r-- | doc/api/crypto.md | 2 | ||||
-rw-r--r-- | doc/api/deprecations.md | 8 | ||||
-rw-r--r-- | doc/api/domain.md | 2 | ||||
-rw-r--r-- | doc/api/events.md | 2 | ||||
-rw-r--r-- | doc/api/fs.md | 30 | ||||
-rw-r--r-- | doc/api/http.md | 8 | ||||
-rw-r--r-- | doc/api/modules.md | 19 | ||||
-rw-r--r-- | doc/api/n-api.md | 10 | ||||
-rw-r--r-- | doc/api/net.md | 7 | ||||
-rw-r--r-- | doc/api/os.md | 13 | ||||
-rw-r--r-- | doc/api/process.md | 78 | ||||
-rw-r--r-- | doc/api/readline.md | 2 | ||||
-rw-r--r-- | doc/api/stream.md | 20 | ||||
-rw-r--r-- | doc/api/tls.md | 45 | ||||
-rw-r--r-- | doc/api/util.md | 6 | ||||
-rw-r--r-- | doc/api/zlib.md | 8 | ||||
-rw-r--r-- | doc/changelogs/CHANGELOG_V010.md | 2 | ||||
-rw-r--r-- | doc/changelogs/CHANGELOG_V012.md | 2 | ||||
-rw-r--r-- | doc/changelogs/CHANGELOG_V4.md | 2 | ||||
-rw-r--r-- | doc/changelogs/CHANGELOG_V5.md | 2 | ||||
-rw-r--r-- | doc/changelogs/CHANGELOG_V6.md | 2 | ||||
-rw-r--r-- | doc/releases.md | 5 |
28 files changed, 189 insertions, 174 deletions
diff --git a/doc/STYLE_GUIDE.md b/doc/STYLE_GUIDE.md index b535d2babcd..efc997f1853 100644 --- a/doc/STYLE_GUIDE.md +++ b/doc/STYLE_GUIDE.md @@ -61,6 +61,10 @@ * References to constructor instances should use camelCase. * References to methods should be used with parentheses: for example, `socket.end()` instead of `socket.end`. +* To draw special attention to a note, adhere to the following guidelines: + * Make the "Note:" label italic, i.e. `*Note*:`. + * Use a capital letter after the "Note:" label. + * Preferably, make the note a new paragraph for better visual distinction. [plugin]: http://editorconfig.org/#download [Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma diff --git a/doc/api/addons.md b/doc/api/addons.md index 772c3c77645..8c08c5492e8 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -113,13 +113,13 @@ specifically to compile Node.js Addons. } ``` -*Note: A version of the `node-gyp` utility is bundled and distributed with +*Note*: A version of the `node-gyp` utility is bundled and distributed with Node.js as part of `npm`. This version is not made directly available for developers to use and is intended only to support the ability to use the `npm install` command to compile and install Addons. Developers who wish to use `node-gyp` directly can install it using the command `npm install -g node-gyp`. See the `node-gyp` [installation instructions][] for -more information, including platform-specific requirements.* +more information, including platform-specific requirements. Once the `binding.gyp` file has been created, use `node-gyp configure` to generate the appropriate project build files for the current platform. This diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 9b3f3f8b4b7..1a61d79e350 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -193,11 +193,11 @@ The character encodings currently supported by Node.js include: * `'hex'` - Encode each byte as two hexadecimal characters. -_Note_: Today's browsers follow the [WHATWG spec] which aliases both 'latin1' and -ISO-8859-1 to win-1252. This means that while doing something like `http.get()`, -if the returned charset is one of those listed in the WHATWG spec it's possible -that the server actually returned win-1252-encoded data, and using `'latin1'` -encoding may incorrectly decode the characters. +*Note*: Today's browsers follow the [WHATWG spec] which aliases both 'latin1' +and ISO-8859-1 to win-1252. This means that while doing something like +`http.get()`, if the returned charset is one of those listed in the WHATWG spec +it's possible that the server actually returned win-1252-encoded data, and +using `'latin1'` encoding may incorrectly decode the characters. ## Buffers and TypedArray <!-- YAML @@ -686,7 +686,7 @@ Returns the actual byte length of a string. This is not the same as [`String.prototype.length`] since that returns the number of *characters* in a string. -*Note* that for `'base64'` and `'hex'`, this function assumes valid input. For +*Note*: For `'base64'` and `'hex'`, this function assumes valid input. For strings that contain non-Base64/Hex-encoded data (e.g. whitespace), the return value might be greater than the length of a `Buffer` created from the string. @@ -1868,8 +1868,8 @@ changes: Returns a new `Buffer` that references the same memory as the original, but offset and cropped by the `start` and `end` indices. -**Note that modifying the new `Buffer` slice will modify the memory in the -original `Buffer` because the allocated memory of the two objects overlap.** +*Note*: Modifying the new `Buffer` slice will modify the memory in the +original `Buffer` because the allocated memory of the two objects overlap. Example: Create a `Buffer` with the ASCII alphabet, take a slice, and then modify one byte from the original `Buffer` diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 7bc523f6466..9fcd06e4689 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -163,9 +163,9 @@ exec('echo "The \\$HOME variable is $HOME"'); //The $HOME variable is escaped in the first instance, but not in the second ``` -**Note: Never pass unsanitised user input to this function. Any input +*Note*: Never pass unsanitised user input to this function. Any input containing shell metacharacters may be used to trigger arbitrary command -execution.** +execution. ```js const exec = require('child_process').exec; @@ -211,8 +211,8 @@ If `timeout` is greater than `0`, the parent will send the signal identified by the `killSignal` property (the default is `'SIGTERM'`) if the child runs longer than `timeout` milliseconds. -*Note: Unlike the exec(3) POSIX system call, `child_process.exec()` does not -replace the existing process and uses a shell to execute the command.* +*Note*: Unlike the exec(3) POSIX system call, `child_process.exec()` does not +replace the existing process and uses a shell to execute the command. If this method is invoked as its [`util.promisify()`][]ed version, it returns a Promise for an object with `stdout` and `stderr` properties. @@ -348,8 +348,8 @@ parent process using the file descriptor (fd) identified using the environment variable `NODE_CHANNEL_FD` on the child process. The input and output on this fd is expected to be line delimited JSON objects. -*Note: Unlike the fork(2) POSIX system call, `child_process.fork()` does -not clone the current process.* +*Note*: Unlike the fork(2) POSIX system call, `child_process.fork()` does +not clone the current process. ### child_process.spawn(command[, args][, options]) <!-- YAML @@ -387,9 +387,9 @@ The `child_process.spawn()` method spawns a new process using the given `command`, with command line arguments in `args`. If omitted, `args` defaults to an empty array. -**Note: If the `shell` option is enabled, do not pass unsanitised user input to +*Note*: If the `shell` option is enabled, do not pass unsanitised user input to this function. Any input containing shell metacharacters may be used to -trigger arbitrary command execution.** +trigger arbitrary command execution. A third argument may be used to specify additional options, with these defaults: @@ -476,13 +476,13 @@ child.on('error', (err) => { }); ``` -*Note: Certain platforms (macOS, Linux) will use the value of `argv[0]` for the -process title while others (Windows, SunOS) will use `command`.* +*Note*: Certain platforms (macOS, Linux) will use the value of `argv[0]` for +the process title while others (Windows, SunOS) will use `command`. -*Note: Node.js currently overwrites `argv[0]` with `process.execPath` on +*Note*: Node.js currently overwrites `argv[0]` with `process.execPath` on startup, so `process.argv[0]` in a Node.js child process will not match the `argv0` parameter passed to `spawn` from the parent, retrieve it with the -`process.argv0` property instead.* +`process.argv0` property instead. #### options.detached <!-- YAML @@ -673,9 +673,11 @@ The `child_process.execFileSync()` method is generally identical to [`child_process.execFile()`][] with the exception that the method will not return until the child process has fully closed. When a timeout has been encountered and `killSignal` is sent, the method won't return until the process has -completely exited. *Note that if the child process intercepts and handles -the `SIGTERM` signal and does not exit, the parent process will still wait -until the child process has exited.* +completely exited. + +*Note*: If the child process intercepts and handles the `SIGTERM` signal and +does not exit, the parent process will still wait until the child process has +exited. If the process times out, or has a non-zero exit code, this method ***will*** throw. The [`Error`][] object will contain the entire result from @@ -729,9 +731,9 @@ If the process times out, or has a non-zero exit code, this method ***will*** throw. The [`Error`][] object will contain the entire result from [`child_process.spawnSync()`][] -**Note: Never pass unsanitised user input to this function. Any input +*Note*: Never pass unsanitised user input to this function. Any input containing shell metacharacters may be used to trigger arbitrary command -execution.** +execution. ### child_process.spawnSync(command[, args][, options]) <!-- YAML @@ -789,9 +791,9 @@ completely exited. Note that if the process intercepts and handles the `SIGTERM` signal and doesn't exit, the parent process will wait until the child process has exited. -**Note: If the `shell` option is enabled, do not pass unsanitised user input to -this function. Any input containing shell metacharacters may be used to -trigger arbitrary command execution.** +*Note*: If the `shell` option is enabled, do not pass unsanitised user input +to this function. Any input containing shell metacharacters may be used to +trigger arbitrary command execution. ## Class: ChildProcess <!-- YAML @@ -1166,8 +1168,8 @@ tracking when the socket is destroyed. To indicate this, the `.connections` property becomes `null`. It is recommended not to use `.maxConnections` when this occurs. -*Note: this function uses [`JSON.stringify()`][] internally to serialize the -`message`.* +*Note*: This function uses [`JSON.stringify()`][] internally to serialize the +`message`. ### child.stderr <!-- YAML diff --git a/doc/api/cli.md b/doc/api/cli.md index 1d3f736967d..c59d80c4efa 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -290,8 +290,8 @@ added: v0.1.3 Print v8 command line options. -Note: v8 options allow words to be separated by both dashes (`-`) or underscores -(`_`). +*Note*: V8 options allow words to be separated by both dashes (`-`) or +underscores (`_`). For example, `--stack-trace-limit` is equivalent to `--stack_trace_limit`. @@ -394,7 +394,7 @@ added: v0.1.32 `':'`-separated list of directories prefixed to the module search path. -_Note: on Windows, this is a `';'`-separated list instead._ +*Note*: On Windows, this is a `';'`-separated list instead. ### `NODE_DISABLE_COLORS=1` @@ -525,7 +525,7 @@ added: v7.7.0 If `--use-openssl-ca` is enabled, this overrides and sets OpenSSL's directory containing trusted certificates. -Note: Be aware that unless the child environment is explicitly set, this +*Note*: Be aware that unless the child environment is explicitly set, this evironment variable will be inherited by any child processes, and if they use OpenSSL, it may cause them to trust the same CAs as node. @@ -537,7 +537,7 @@ added: v7.7.0 If `--use-openssl-ca` is enabled, this overrides and sets OpenSSL's file containing trusted certificates. -Note: Be aware that unless the child environment is explicitly set, this +*Note*: Be aware that unless the child environment is explicitly set, this evironment variable will be inherited by any child processes, and if they use OpenSSL, it may cause them to trust the same CAs as node. diff --git a/doc/api/console.md b/doc/api/console.md index ca4ff637d9e..f0fce96549e 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -121,8 +121,8 @@ console.assert(false, 'Whoops %s', 'didn\'t work'); // AssertionError: Whoops didn't work ``` -*Note: the `console.assert()` method is implemented differently in Node.js -than the `console.assert()` method [available in browsers][web-api-assert].* +*Note*: The `console.assert()` method is implemented differently in Node.js +than the `console.assert()` method [available in browsers][web-api-assert]. Specifically, in browsers, calling `console.assert()` with a falsy assertion will cause the `message` to be printed to the console without @@ -282,10 +282,10 @@ console.timeEnd('100-elements'); // prints 100-elements: 225.438ms ``` -*Note: As of Node.js v6.0.0, `console.timeEnd()` deletes the timer to avoid +*Note*: As of Node.js v6.0.0, `console.timeEnd()` deletes the timer to avoid leaking it. On older versions, the timer persisted. This allowed `console.timeEnd()` to be called multiple times for the same label. This -functionality was unintended and is no longer supported.* +functionality was unintended and is no longer supported. ### console.trace([message][, ...args]) <!-- YAML diff --git a/doc/api/crypto.md b/doc/api/crypto.md index b217c655d0b..5eae3f56483 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -1820,7 +1820,7 @@ comparing HMAC digests or secret values like authentication cookies or `a` and `b` must both be `Buffer`s, `TypedArray`s, or `DataView`s, and they must have the same length. -**Note**: Use of `crypto.timingSafeEqual` does not guarantee that the +*Note*: Use of `crypto.timingSafeEqual` does not guarantee that the *surrounding* code is timing-safe. Care should be taken to ensure that the surrounding code does not introduce timing vulnerabilities. diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 96e9f927d34..b66b9c5a5c5 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -531,8 +531,8 @@ Type: Documentation-only The `http` module `ServerResponse.prototype.writeHeader()` API has been deprecated. Please use `ServerResponse.prototype.writeHead()` instead. -*Note*: The `ServerResponse.prototype.writeHeader()` method was never documented -as an officially supported API. +*Note*: The `ServerResponse.prototype.writeHeader()` method was never +documented as an officially supported API. <a id="DEP0064"></a> ### DEP0064: tls.createSecurePair() @@ -568,8 +568,8 @@ properties have been deprecated. Please instead use one of the public methods `outgoingMessage.removeHeader()`, `outgoingMessage.setHeader()`) for working with outgoing headers. -*Note*: `outgoingMessage._headers` and `outgoingMessage._headerNames` were never -documented as officially supported properties. +*Note*: `outgoingMessage._headers` and `outgoingMessage._headerNames` were +never documented as officially supported properties. <a id="DEP0067"></a> ### DEP0067: OutgoingMessage.prototype.\_renderHeaders diff --git a/doc/api/domain.md b/doc/api/domain.md index d4952751647..957a32af151 100644 --- a/doc/api/domain.md +++ b/doc/api/domain.md @@ -115,7 +115,7 @@ if (cluster.isMaster) { d.on('error', (er) => { console.error(`error ${er.stack}`); - // Note: we're in dangerous territory! + // Note: We're in dangerous territory! // By definition, something unexpected occurred, // which we probably didn't want. // Anything can happen now! Be very careful! diff --git a/doc/api/events.md b/doc/api/events.md index da13a118c70..ff6fbe9bb9a 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -142,7 +142,7 @@ myEmitter.emit('error', new Error('whoops!')); To guard against crashing the Node.js process, a listener can be registered on the [`process` object's `uncaughtException` event][] or the [`domain`][] module -can be used. (_Note, however, that the `domain` module has been deprecated_) +can be used. (Note, however, that the `domain` module has been deprecated.) ```js const myEmitter = new MyEmitter(); diff --git a/doc/api/fs.md b/doc/api/fs.md index beb60973bbd..a3edb245ed1 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -194,7 +194,7 @@ filesystems that allow for non-UTF-8 filenames. For most typical uses, working with paths as Buffers will be unnecessary, as the string API converts to and from UTF-8 automatically. -*Note* that on certain file systems (such as NTFS and HFS+) filenames +*Note*: On certain file systems (such as NTFS and HFS+) filenames will always be encoded as UTF-8. On such file systems, passing non-UTF-8 encoded Buffers to `fs` functions will not work as expected. @@ -1546,8 +1546,8 @@ On Linux, positional writes don't work when the file is opened in append mode. The kernel ignores the position argument and always appends the data to the end of the file. -*Note*: The behavior of `fs.open()` is platform-specific for some flags. As such, -opening a directory on macOS and Linux with the `'a+'` flag - see example +*Note*: The behavior of `fs.open()` is platform-specific for some flags. As +such, opening a directory on macOS and Linux with the `'a+'` flag - see example below - will return an error. In contrast, on Windows and FreeBSD, a file descriptor will be returned. @@ -2156,9 +2156,9 @@ effectively stopping watching of `filename`. Calling `fs.unwatchFile()` with a filename that is not being watched is a no-op, not an error. -*Note*: [`fs.watch()`][] is more efficient than `fs.watchFile()` and `fs.unwatchFile()`. -`fs.watch()` should be used instead of `fs.watchFile()` and `fs.unwatchFile()` -when possible. +*Note*: [`fs.watch()`][] is more efficient than `fs.watchFile()` and +`fs.unwatchFile()`. `fs.watch()` should be used instead of `fs.watchFile()` +and `fs.unwatchFile()` when possible. ## fs.utimes(path, atime, mtime, callback) <!-- YAML @@ -2185,7 +2185,7 @@ changes: Change file timestamps of the file referenced by the supplied path. -Note: the arguments `atime` and `mtime` of the following related functions +*Note*: The arguments `atime` and `mtime` of the following related functions follow these rules: - The value should be a Unix timestamp in seconds. For example, `Date.now()` @@ -2366,11 +2366,12 @@ These stat objects are instances of `fs.Stat`. To be notified when the file was modified, not just accessed, it is necessary to compare `curr.mtime` and `prev.mtime`. -*Note*: when an `fs.watchFile` operation results in an `ENOENT` error, it will - invoke the listener once, with all the fields zeroed (or, for dates, the Unix - Epoch). In Windows, `blksize` and `blocks` fields will be `undefined`, instead - of zero. If the file is created later on, the listener will be called again, - with the latest stat objects. This is a change in functionality since v0.10. +*Note*: When an `fs.watchFile` operation results in an `ENOENT` error, it +will invoke the listener once, with all the fields zeroed (or, for dates, the +Unix Epoch). In Windows, `blksize` and `blocks` fields will be `undefined`, +instead of zero. If the file is created later on, the listener will be called +again, with the latest stat objects. This is a change in functionality since +v0.10. *Note*: [`fs.watch()`][] is more efficient than `fs.watchFile` and `fs.unwatchFile`. `fs.watch` should be used instead of `fs.watchFile` and @@ -2577,8 +2578,9 @@ Synchronous versions of [`fs.write()`][]. Returns the number of bytes written. ## FS Constants -The following constants are exported by `fs.constants`. **Note:** Not every -constant will be available on every operating system. +The following constants are exported by `fs.constants`. + +*Note*: Not every constant will be available on every operating system. ### File Access Constants diff --git a/doc/api/http.md b/doc/api/http.md index 25b484c6a37..afe08be89cb 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -268,8 +268,8 @@ Until the data is consumed, the `'end'` event will not fire. Also, until the data is read it will consume memory that can eventually lead to a 'process out of memory' error. -Note: Node.js does not check whether Content-Length and the length of the body -which has been transmitted are equal or not. +*Note*: Node.js does not check whether Content-Length and the length of the +body which has been transmitted are equal or not. The request implements the [Writable Stream][] interface. This is an [`EventEmitter`][] with the following events: @@ -765,7 +765,7 @@ Begin accepting connections on the specified `port` and `hostname`. If the [unspecified IPv6 address][] (`::`) when IPv6 is available, or the [unspecified IPv4 address][] (`0.0.0.0`) otherwise. -*Note*: in most operating systems, listening to the +*Note*: In most operating systems, listening to the [unspecified IPv6 address][] (`::`) may cause the `net.Server` to also listen on the [unspecified IPv4 address][] (`0.0.0.0`). @@ -1177,7 +1177,7 @@ the second parameter specifies how to encode it into a byte stream. By default the `encoding` is `'utf8'`. `callback` will be called when this chunk of data is flushed. -**Note**: This is the raw HTTP body and has nothing to do with +*Note*: This is the raw HTTP body and has nothing to do with higher-level multi-part body encodings that may be used. The first time [`response.write()`][] is called, it will send the buffered diff --git a/doc/api/modules.md b/doc/api/modules.md index d09e58f5cb8..adbefb81209 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -348,9 +348,9 @@ If this was in a folder at `./some-library`, then This is the extent of Node.js's awareness of package.json files. -Note: If the file specified by the `"main"` entry of `package.json` is missing -and can not be resolved, Node.js will report the entire module as missing with -the default error: +*Note*: If the file specified by the `"main"` entry of `package.json` is +missing and can not be resolved, Node.js will report the entire module as +missing with the default error: ```txt Error: Cannot find module 'some-library' @@ -401,8 +401,9 @@ same module resolution semantics. If the `NODE_PATH` environment variable is set to a colon-delimited list of absolute paths, then Node.js will search those paths for modules if they -are not found elsewhere. (Note: On Windows, `NODE_PATH` is delimited by -semicolons instead of colons.) +are not found elsewhere. + +*Note*: On Windows, `NODE_PATH` is delimited by semicolons instead of colons. `NODE_PATH` was originally created to support loading modules from varying paths before the current [module resolution][] algorithm was frozen. @@ -627,10 +628,10 @@ added: v0.5.1 The `module.require` method provides a way to load a module as if `require()` was called from the original module. -*Note*: In order to do this, it is necessary to get a reference to the `module` -object. Since `require()` returns the `module.exports`, and the `module` is -typically *only* available within a specific module's code, it must be -explicitly exported in order to be used. +*Note*: In order to do this, it is necessary to get a reference to the +`module` object. Since `require()` returns the `module.exports`, and the +`module` is typically *only* available within a specific module's code, it must +be explicitly exported in order to be used. [`Error`]: errors.html#errors_class_error [module resolution]: #modules_all_together diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 6136929e4a9..e3ed8809836 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -241,7 +241,7 @@ typedef struct napi_extended_error_info { [`napi_get_last_error_info`][] returns the information for the last N-API call that was made. -**Note:** Do not rely on the content or format of any of the extended +*Note*: Do not rely on the content or format of any of the extended information as it is not subject to SemVer and may change at any time. It is intended only for logging purposes. @@ -263,7 +263,7 @@ Returns `napi_ok` if the API succeeded. This API retrieves a `napi_extended_error_info` structure with information about the last error that occured. -**Note:** Do not rely on the content or format of any of the extended +*Note*: Do not rely on the content or format of any of the extended information as it is not subject to SemVer and may change at any time. It is intended only for logging purposes. @@ -1138,7 +1138,7 @@ This API allocates a `node::Buffer` object and initializes it with data backed by the passed in buffer. While this is still a fully-supported data structure, in most cases using a TypedArray will suffice. -**Note:** For Node.js >=4 `Buffers` are Uint8Arrays. +*Note*: For Node.js >=4 `Buffers` are Uint8Arrays. #### *napi_create_function* <!-- YAML @@ -2497,7 +2497,7 @@ This API allows an add-on author to create a function object in native code. This is the primary mechanism to allow calling *into* the add-on's native code *from* Javascript. -**Note:** The newly created function is not automatically visible from +*Note*: The newly created function is not automatically visible from script after this call. Instead, a property must be explicitly set on any object that is visible to JavaScript, in order for the function to be accessible from script. @@ -2530,7 +2530,7 @@ const myaddon = require('./addon'); myaddon.sayHello(); ``` -**Note:** The string passed to require is not necessarily the name passed into +*Note*: The string passed to require is not necessarily the name passed into `NAPI_MODULE` in the earlier snippet but the name of the target in `binding.gyp` responsible for creating the `.node` file. diff --git a/doc/api/net.md b/doc/api/net.md index 8eea2d4bcd4..982a5a0aeb7 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -185,10 +185,11 @@ by the OS through sysctl settings such as `tcp_max_syn_backlog` and `somaxconn` on Linux. The default value of this parameter is 511 (not 512). -Note: +*Note*: * All [`net.Socket`][] are set to `SO_REUSEADDR` (See [socket(7)][] for details). + * The `server.listen()` method may be called multiple times. Each subsequent call will *re-open* the server using the provided options. @@ -294,7 +295,7 @@ If `host` is omitted, the server will accept connections on the [unspecified IPv6 address][] (`::`) when IPv6 is available, or the [unspecified IPv4 address][] (`0.0.0.0`) otherwise. -*Note*: in most operating systems, listening to the +*Note*: In most operating systems, listening to the [unspecified IPv6 address][] (`::`) may cause the `net.Server` to also listen on the [unspecified IPv4 address][] (`0.0.0.0`). @@ -852,7 +853,7 @@ Possible signatures: * [`net.createConnection(port[, host][, connectListener])`][`net.createConnection(port, host)`] for TCP connections. -*Note*: the [`net.connect()`][] function is an alias to this function. +*Note*: The [`net.connect()`][] function is an alias to this function. ### net.createConnection(options[, connectListener]) <!-- YAML diff --git a/doc/api/os.md b/doc/api/os.md index b9f2775ce6a..6afa69d39ed 100644 --- a/doc/api/os.md +++ b/doc/api/os.md @@ -165,8 +165,8 @@ For example: ] ``` -*Note*: Because `nice` values are UNIX-specific, on Windows the `nice` values of -all processors are always 0. +*Note*: Because `nice` values are UNIX-specific, on Windows the `nice` values +of all processors are always 0. ## os.endianness() <!-- YAML @@ -328,8 +328,8 @@ added: v0.3.3 The `os.release()` method returns a string identifying the operating system release. -*Note*: On POSIX systems, the operating system release is determined by calling -uname(3). On Windows, `GetVersionExW()` is used. Please see +*Note*: On POSIX systems, the operating system release is determined by +calling uname(3). On Windows, `GetVersionExW()` is used. Please see https://en.wikipedia.org/wiki/Uname#Examples for more information. ## os.tmpdir() @@ -406,8 +406,9 @@ operating system response. ## OS Constants -The following constants are exported by `os.constants`. **Note:** Not all -constants will be available on every operating system. +The following constants are exported by `os.constants`. + +*Note*: Not all constants will be available on every operating system. ### Signal Constants <!-- YAML diff --git a/doc/api/process.md b/doc/api/process.md index 40ec3e0b1aa..fda57bf431c 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -1005,7 +1005,7 @@ if (process.getegid) { ``` *Note*: This function is only available on POSIX platforms (i.e. not Windows -or Android) +or Android). ## process.geteuid() <!-- YAML @@ -1023,8 +1023,8 @@ if (process.geteuid) { } ``` -*Note*: This function is only available on POSIX platforms (i.e. not Windows or -Android) +*Note*: This function is only available on POSIX platforms (i.e. not Windows +or Android). ## process.getgid() <!-- YAML @@ -1042,8 +1042,8 @@ if (process.getgid) { } ``` -*Note*: This function is only available on POSIX platforms (i.e. not Windows or -Android) +*Note*: This function is only available on POSIX platforms (i.e. not Windows +or Android). ## process.getgroups() @@ -1057,8 +1057,8 @@ The `process.getgroups()` method returns an array with the supplementary group IDs. POSIX leaves it unspecified if the effective group ID is included but Node.js ensures it always is. -*Note*: This function is only available on POSIX platforms (i.e. not Windows or -Android) +*Note*: This function is only available on POSIX platforms (i.e. not Windows +or Android). ## process.getuid() <!-- YAML @@ -1076,8 +1076,8 @@ if (process.getuid) { } ``` -*Note*: This function is only available on POSIX platforms (i.e. not Windows or -Android) +*Note*: This function is only available on POSIX platforms (i.e. not Windows +or Android). ## process.hrtime([time]) <!-- YAML @@ -1139,8 +1139,8 @@ process.setgid(1000); // drop root gid console.log(process.getgroups()); // [ 27, 30, 46, 1000 ] ``` -*Note*: This function is only available on POSIX platforms (i.e. not Windows or -Android) +*Note*: This function is only available on POSIX platforms (i.e. not Windows +or Android). ## process.kill(pid[, signal]) <!-- YAML @@ -1162,9 +1162,9 @@ case, a signal of `0` can be used to test for the existence of a process. Windows platforms will throw an error if the `pid` is used to kill a process group. -*Note*:Even though the name of this function is `process.kill()`, it is really -just a signal sender, like the `kill` system call. The signal sent may do -something other than kill the target process. +*Note*: Even though the name of this function is `process.kill()`, it is +really just a signal sender, like the `kill` system call. The signal sent may +do something other than kill the target process. For example: @@ -1181,8 +1181,8 @@ setTimeout(() => { process.kill(process.pid, 'SIGHUP'); ``` -*Note*: When `SIGUSR1` is received by a Node.js process, Node.js will start the -debugger, see [Signal Events][]. +*Note*: When `SIGUSR1` is received by a Node.js process, Node.js will start +the debugger, see [Signal Events][]. ## process.mainModule <!-- YAML @@ -1331,7 +1331,7 @@ function definitelyAsync(arg, cb) { } ``` -*Note*: the next tick queue is completely drained on each pass of the +*Note*: The next tick queue is completely drained on each pass of the event loop **before** additional I/O is processed. As a result, recursively setting nextTick callbacks will block any I/O from happening, just like a `while(true);` loop. @@ -1430,7 +1430,7 @@ If Node.js was not spawned with an IPC channel, `process.send()` will be `undefined`. *Note*: This function uses [`JSON.stringify()`][] internally to serialize the -`message`.* +`message`. ## process.setegid(id) <!-- YAML @@ -1456,8 +1456,8 @@ if (process.getegid && process.setegid) { } ``` -*Note*: This function is only available on POSIX platforms (i.e. not Windows or -Android) +*Note*: This function is only available on POSIX platforms (i.e. not Windows +or Android). ## process.seteuid(id) @@ -1484,8 +1484,8 @@ if (process.geteuid && process.seteuid) { } ``` -*Note*: This function is only available on POSIX platforms (i.e. not Windows or -Android) +*Note*: This function is only available on POSIX platforms (i.e. not Windows +or Android). ## process.setgid(id) <!-- YAML @@ -1511,8 +1511,8 @@ if (process.getgid && process.setgid) { } ``` -*Note*: This function is only available on POSIX platforms (i.e. not Windows or -Android) +*Note*: This function is only available on POSIX platforms (i.e. not Windows +or Android). ## process.setgroups(groups) <!-- YAML @@ -1527,8 +1527,8 @@ to have `root` or the `CAP_SETGID` capability. The `groups` array can contain numeric group IDs, group names or both. -*Note*: This function is only available on POSIX platforms (i.e. not Windows or -Android) +*Note*: This function is only available on POSIX platforms (i.e. not Windows +or Android). ## process.setuid(id) <!-- YAML @@ -1552,8 +1552,8 @@ if (process.getuid && process.setuid) { } ``` -*Note*: This function is only available on POSIX platforms (i.e. not Windows or -Android) +*Note*: This function is only available on POSIX platforms (i.e. not Windows +or Android). ## process.stderr @@ -1565,7 +1565,7 @@ The `process.stderr` property returns a stream connected to stream) unless fd `2` refers to a file, in which case it is a [Writable][] stream. -Note: `process.stderr` differs from other Node.js streams in important ways, +*Note*: `process.stderr` differs from other Node.js streams in important ways, see [note on process I/O][] for more information. ## process.stdin @@ -1617,7 +1617,7 @@ For example, to copy process.stdin to process.stdout: process.stdin.pipe(process.stdout); ``` -Note: `process.stdout` differs from other Node.js streams in important ways, +*Note*: `process.stdout` differs from other Node.js streams in important ways, see [note on process I/O][] for more information. ### A note on process I/O @@ -1680,14 +1680,14 @@ The `process.title` property returns the current process title (i.e. returns the current value of `ps`). Assigning a new value to `process.title` modifies the current value of `ps`. -*Note*: When a new value is assigned, different platforms will impose different -maximum length restrictions on the title. Usually such restrictions are quite -limited. For instance, on Linux and macOS, `process.title` is limited to the -size of the binary name plus the length of the command line arguments because -setting the `process.title` overwrites the `argv` memory of the process. -Node.js v0.8 allowed for longer process title strings by also overwriting the -`environ` memory but that was potentially insecure and confusing in some -(rather obscure) cases. +*Note*: When a new value is assigned, different platforms will impose +different maximum length restrictions on the title. Usually such restrictions +are quite limited. For instance, on Linux and macOS, `process.title` is limited +to the size of the binary name plus the length of the command line arguments +because setting the `process.title` overwrites the `argv` memory of the +process. Node.js v0.8 allowed for longer process title strings by also +overwriting the `environ` memory but that was potentially insecure and +confusing in some (rather obscure) cases. ## process.umask([mask]) <!-- YAML @@ -1720,7 +1720,7 @@ added: v0.5.0 The `process.uptime()` method returns the number of seconds the current Node.js process has been running. -*Note*: the return value includes fractions of a second. Use `Math.floor()` +*Note*: The return value includes fractions of a second. Use `Math.floor()` to get whole seconds. ## process.version diff --git a/doc/api/readline.md b/doc/api/readline.md index 52220a18222..136d0e63ceb 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -27,7 +27,7 @@ rl.question('What do you think of Node.js? ', (answer) => { }); ``` -*Note* Once this code is invoked, the Node.js application will not +*Note*: Once this code is invoked, the Node.js application will not terminate until the `readline.Interface` is closed because the interface waits for data to be received on the `input` stream. diff --git a/doc/api/stream.md b/doc/api/stream.md index d5c25517749..d8c27ea1c4c 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -893,7 +893,7 @@ A Readable stream in object mode will always return a single item from a call to [`readable.read(size)`][stream-read], regardless of the value of the `size` argument. -*Note:* If the `readable.read()` method returns a chunk of data, a `'data'` +*Note*: If the `readable.read()` method returns a chunk of data, a `'data'` event will also be emitted. *Note*: Calling [`stream.read([size])`][stream-read] after the [`'end'`][] @@ -1346,7 +1346,7 @@ resource. *Note*: [Transform][] streams provide their own implementation of the [`writable._write()`][stream-_write]. -*Note*: **This function MUST NOT be called by application code directly.** It +*Note*: This function MUST NOT be called by application code directly. It should be implemented by child classes, and called only by the internal Writable class methods only. @@ -1381,7 +1381,7 @@ user programs. * `callback` {Function} A callback function (optionally with an error argument) to be invoked when processing is complete for the supplied chunks. -*Note*: **This function MUST NOT be called by application code directly.** It +*Note*: This function MUST NOT be called by application code directly. It should be implemented by child classes, and called only by the internal Writable class methods only. @@ -1536,7 +1536,7 @@ const myReadable = new Readable({ * `size` {number} Number of bytes to read asynchronously -*Note*: **This function MUST NOT be called by application code directly.** It +*Note*: This function MUST NOT be called by application code directly. It should be implemented by child classes, and called only by the internal Readable class methods only. @@ -1684,10 +1684,10 @@ Because JavaScript does not have support for multiple inheritance, the `stream.Duplex` class is extended to implement a [Duplex][] stream (as opposed to extending the `stream.Readable` *and* `stream.Writable` classes). -*Note*: The `stream.Duplex` class prototypically inherits from `stream.Readable` -and parasitically from `stream.Writable`, but `instanceof` will work properly -for both base classes due to overriding [`Symbol.hasInstance`][] -on `stream.Writable`. +*Note*: The `stream.Duplex` class prototypically inherits from +`stream.Readable` and parasitically from `stream.Writable`, but `instanceof` +will work properly for both base classes due to overriding +[`Symbol.hasInstance`][] on `stream.Writable`. Custom Duplex streams *must* call the `new stream.Duplex([options])` constructor and implement *both* the `readable._read()` and @@ -1916,7 +1916,7 @@ after all data has been output, which occurs after the callback in * `callback` {Function} A callback function (optionally with an error argument and data) to be called when remaining data has been flushed. -*Note*: **This function MUST NOT be called by application code directly.** It +*Note*: This function MUST NOT be called by application code directly. It should be implemented by child classes, and called only by the internal Readable class methods only. @@ -1951,7 +1951,7 @@ user programs. argument and data) to be called after the supplied `chunk` has been processed. -*Note*: **This function MUST NOT be called by application code directly.** It +*Note*: This function MUST NOT be called by application code directly. It should be implemented by child classes, and called only by the internal Readable class methods only. diff --git a/doc/api/tls.md b/doc/api/tls.md index 88f93f51d1d..ba1cb5a6975 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -488,11 +488,9 @@ changes: * `secureContext`: Optional TLS context object created with [`tls.createSecureContext()`][]. If a `secureContext` is _not_ provided, one will be created by passing the entire `options` object to - `tls.createSecureContext()`. *Note*: In effect, all - [`tls.createSecureContext()`][] options can be provided, but they will be - _completely ignored_ unless the `secureContext` option is missing. - * ...: Optional [`tls.createSecureContext()`][] options can be provided, see - the `secureContext` option for more information. + `tls.createSecureContext()`. + * ...: Optional [`tls.createSecureContext()`][] options that are used if the + `secureContext` option is missing, otherwise they are ignored. Construct a new `tls.TLSSocket` object from an existing TCP socket. @@ -667,8 +665,8 @@ added: v0.11.4 Returns the TLS session ticket or `undefined` if no session was negotiated. -*Note*: This only works with client TLS sockets. Useful only for debugging, for -session reuse provide `session` option to [`tls.connect()`][]. +*Note*: This only works with client TLS sockets. Useful only for debugging, +for session reuse provide `session` option to [`tls.connect()`][]. ### tlsSocket.localAddress <!-- YAML @@ -809,12 +807,10 @@ changes: * `secureContext`: Optional TLS context object created with [`tls.createSecureContext()`][]. If a `secureContext` is _not_ provided, one will be created by passing the entire `options` object to - `tls.createSecureContext()`. *Note*: In effect, all - [`tls.createSecureContext()`][] options can be provided, but they will be - _completely ignored_ unless the `secureContext` option is missing. + `tls.createSecureContext()`. * `lookup`: {Function} Custom lookup function. Defaults to [`dns.lookup()`][]. - * ...: Optional [`tls.createSecureContext()`][] options can be provided, see - the `secureContext` option for more information. + * ...: Optional [`tls.createSecureContext()`][] options that are used if the + `secureContext` option is missing, otherwise they are ignored. * `callback` {Function} The `callback` function, if specified, will be added as a listener for the @@ -905,8 +901,8 @@ added: v0.11.3 Same as [`tls.connect()`][] except that `port` and `host` can be provided as arguments instead of options. -*Note*: A port or host option, if specified, will take precedence over any port -or host argument. +*Note*: A port or host option, if specified, will take precedence over any +port or host argument. ## tls.createSecureContext(options) @@ -971,8 +967,6 @@ changes: preferences instead of the client's. When `true`, causes `SSL_OP_CIPHER_SERVER_PREFERENCE` to be set in `secureOptions`, see [OpenSSL Options][] for more information. - *Note*: [`tls.createServer()`][] sets the default value to `true`, other - APIs that create secure contexts leave it unset. * `ecdhCurve` {string} A string describing a named curve to use for ECDH key agreement or `false` to disable ECDH. Defaults to [`tls.DEFAULT_ECDH_CURVE`]. Use [`crypto.getCurves()`][] to obtain a list @@ -994,9 +988,16 @@ changes: [OpenSSL Options][]. * `sessionIdContext` {string} Optional opaque identifier used by servers to ensure session state is not shared between applications. Unused by clients. - *Note*: [`tls.createServer()`][] uses a 128 bit truncated SHA1 hash value - generated from `process.argv`, other APIs that create secure contexts - have no default value. + +*Note*: + +* [`tls.createServer()`][] sets the default value of the + `honorCipherOrder` option to `true`, other APIs that create secure contexts + leave it unset. + +* [`tls.createServer()`][] uses a 128 bit truncated SHA1 hash value + generated from `process.argv` as the default value of the `sessionIdContext` + option, other APIs that create secure contexts have no default value. The `tls.createSecureContext()` method creates a credentials object. @@ -1060,8 +1061,7 @@ changes: server will time out. See [SSL_CTX_set_timeout] for more details. * `ticketKeys`: A 48-byte `Buffer` instance consisting of a 16-byte prefix, a 16-byte HMAC key, and a 16-byte AES key. This can be used to accept TLS - session tickets on multiple instances of the TLS server. *Note* that this is - automatically shared between `cluster` module workers. + session tickets on multiple instances of the TLS server. * ...: Any [`tls.createSecureContext()`][] options can be provided. For servers, the identity options (`pfx` or `key`/`cert`) are usually required. * `secureConnectionListener` {Function} @@ -1069,6 +1069,9 @@ changes: Creates a new [tls.Server][]. The `secureConnectionListener`, if provided, is automatically set as a listener for the [`'secureConnection'`][] event. +*Note*: The `ticketKeys` options is automatically shared between `cluster` +module workers. + The following illustrates a simple echo server: ```js diff --git a/doc/api/util.md b/doc/api/util.md index 7a9a779cbab..07d230886b9 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -151,9 +151,9 @@ changes: description: The `constructor` parameter can refer to an ES6 class now. --> -_Note: usage of `util.inherits()` is discouraged. Please use the ES6 `class` and -`extends` keywords to get language level inheritance support. Also note that -the two styles are [semantically incompatible][]._ +*Note*: Usage of `util.inherits()` is discouraged. Please use the ES6 `class` +and `extends` keywords to get language level inheritance support. Also note +that the two styles are [semantically incompatible][]. * `constructor` {Function} * `superConstructor` {Function} diff --git a/doc/api/zlib.md b/doc/api/zlib.md index f889914bb0b..e159a70ce77 100644 --- a/doc/api/zlib.md +++ b/doc/api/zlib.md @@ -54,8 +54,8 @@ the compression encodings accepted by the client. The [`Content-Encoding`][] header is used to identify the compression encodings actually applied to a message. -**Note: the examples given below are drastically simplified to show -the basic concept.** Using `zlib` encoding can be expensive, and the results +*Note*: the examples given below are drastically simplified to show +the basic concept. Using `zlib` encoding can be expensive, and the results ought to be cached. See [Memory Usage Tuning][] for more information on the speed/memory/compression tradeoffs involved in `zlib` usage. @@ -100,7 +100,7 @@ http.createServer((request, response) => { acceptEncoding = ''; } - // Note: this is not a conformant accept-encoding parser. + // Note: This is not a conformant accept-encoding parser. // See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3 if (acceptEncoding.match(/\bdeflate\b/)) { response.writeHead(200, { 'Content-Encoding': 'deflate' }); @@ -437,7 +437,7 @@ added: v0.5.8 Returns a new [DeflateRaw][] object with an [options][]. -**Note:** The zlib library rejects requests for 256-byte windows (i.e., +*Note*: The zlib library rejects requests for 256-byte windows (i.e., `{ windowBits: 8 }` in `options`). An `Error` will be thrown when creating a [DeflateRaw][] object with this specific value of the `windowBits` option. diff --git a/doc/changelogs/CHANGELOG_V010.md b/doc/changelogs/CHANGELOG_V010.md index 1d3cde8b491..2b247a12e70 100644 --- a/doc/changelogs/CHANGELOG_V010.md +++ b/doc/changelogs/CHANGELOG_V010.md @@ -70,7 +70,7 @@ * [io.js](CHANGELOG_IOJS.md) * [Archive](CHANGELOG_ARCHIVE.md) -**Note:** Node.js v0.10 is covered by the +*Note*: Node.js v0.10 is covered by the [Node.js Long Term Support Plan](https://github.com/nodejs/LTS) and will be maintained until October 2016. diff --git a/doc/changelogs/CHANGELOG_V012.md b/doc/changelogs/CHANGELOG_V012.md index cbacd47f692..436ec48c9c2 100644 --- a/doc/changelogs/CHANGELOG_V012.md +++ b/doc/changelogs/CHANGELOG_V012.md @@ -38,7 +38,7 @@ * [io.js](CHANGELOG_IOJS.md) * [Archive](CHANGELOG_ARCHIVE.md) -**Note:** Node.js v0.12 is covered by the +*Note*: Node.js v0.12 is covered by the [Node.js Long Term Support Plan](https://github.com/nodejs/LTS) and will be maintained until December 31st, 2016. diff --git a/doc/changelogs/CHANGELOG_V4.md b/doc/changelogs/CHANGELOG_V4.md index 6c8aa895b5e..94385c032ae 100644 --- a/doc/changelogs/CHANGELOG_V4.md +++ b/doc/changelogs/CHANGELOG_V4.md @@ -57,7 +57,7 @@ * [Archive](CHANGELOG_ARCHIVE.md) -**Note:** Node.js v4 is covered by the +*Note*: Node.js v4 is covered by the [Node.js Long Term Support Plan](https://github.com/nodejs/LTS) and will be supported actively until April 2017 and maintained until April 2018. diff --git a/doc/changelogs/CHANGELOG_V5.md b/doc/changelogs/CHANGELOG_V5.md index 5fefbcc81a6..fdf265206fd 100644 --- a/doc/changelogs/CHANGELOG_V5.md +++ b/doc/changelogs/CHANGELOG_V5.md @@ -38,7 +38,7 @@ * [io.js](CHANGELOG_IOJS.md) * [Archive](CHANGELOG_ARCHIVE.md) -**Note:** Official support for the v5 release line is scheduled to expire +*Note*: Official support for the v5 release line is scheduled to expire around June 2016. Users of v5 should upgrade to [Node.js v6](CHANGELOG_V6.md). <a id="5.12.0"></a> diff --git a/doc/changelogs/CHANGELOG_V6.md b/doc/changelogs/CHANGELOG_V6.md index 48a45c94e45..c084eebceee 100644 --- a/doc/changelogs/CHANGELOG_V6.md +++ b/doc/changelogs/CHANGELOG_V6.md @@ -45,7 +45,7 @@ * [io.js](CHANGELOG_IOJS.md) * [Archive](CHANGELOG_ARCHIVE.md) -**Note:** Node.js v6 is covered by the +*Note*: Node.js v6 is covered by the [Node.js Long Term Support Plan](https://github.com/nodejs/LTS) and will be supported actively until April 2018 and maintained until April 2019. diff --git a/doc/releases.md b/doc/releases.md index 6433eeeacb1..eafc906026d 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -86,7 +86,7 @@ This macro is used to signal an ABI version for native addons. It currently has The general rule is to bump this version when there are _breaking ABI_ changes and also if there are non-trivial API changes. The rules are not yet strictly defined, so if in doubt, please confer with someone that will have a more informed perspective, such as a member of the NAN team. -**Note** that it is current TSC policy to bump major version when ABI changes. If you see a need to bump `NODE_MODULE_VERSION` then you should consult the TSC. Commits may need to be reverted or a major version bump may need to happen. +*Note*: It is current TSC policy to bump major version when ABI changes. If you see a need to bump `NODE_MODULE_VERSION` then you should consult the TSC. Commits may need to be reverted or a major version bump may need to happen. ### 3. Update the Changelog @@ -279,7 +279,8 @@ Use `tools/release.sh` to promote and sign the build. When run, it will perform If you didn't wait for ARM builds in the previous step before promoting the release, you should re-run `tools/release.sh` after the ARM builds have finished. That will move the ARM artifacts into the correct location. You will be prompted to re-sign SHASUMS256.txt. -Note: it is possible to only sign a release by running `./tools/release.sh -s vX.Y.Z`. +*Note*: It is possible to only sign a release by running +`./tools/release.sh -s vX.Y.Z`. ### 13. Check the Release |