From deb89b051f28e2d662ceb26f24b46c00a89ee054 Mon Sep 17 00:00:00 2001 From: Nick Schonning Date: Sat, 31 Aug 2019 18:42:48 -0400 Subject: [PATCH] doc: indent ordered list child content Markdownlint flags this with MD029 rule. Markdown renders will usually use list continuation number if it can. Explicitly adding it to the list item child scope makes it clearer. --- doc/api/dns.md | 86 ++++++----- doc/guides/backporting-to-release-lines.md | 46 +++--- doc/guides/updating-root-certs.md | 172 ++++++++++----------- 3 files changed, 153 insertions(+), 151 deletions(-) diff --git a/doc/api/dns.md b/doc/api/dns.md index a22af1280ac531..43f78af7c7e0fd 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -6,52 +6,54 @@ The `dns` module contains functions belonging to two different categories: -1) Functions that use the underlying operating system facilities to perform -name resolution, and that do not necessarily perform any network communication. -This category contains only one function: [`dns.lookup()`][]. **Developers -looking to perform name resolution in the same way that other applications on -the same operating system behave should use [`dns.lookup()`][].** +1. Functions that use the underlying operating system facilities to perform + name resolution, and that do not necessarily perform any network + communication. + This category contains only one function: [`dns.lookup()`][]. **Developers + looking to perform name resolution in the same way that other applications + on the same operating system behave should use [`dns.lookup()`][].** -For example, looking up `iana.org`. + For example, looking up `iana.org`. -```js -const dns = require('dns'); - -dns.lookup('iana.org', (err, address, family) => { - console.log('address: %j family: IPv%s', address, family); -}); -// address: "192.0.43.8" family: IPv4 -``` - -2) Functions that connect to an actual DNS server to perform name resolution, -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 -developers who do not want to use the underlying operating system's facilities -for name resolution, and instead want to _always_ perform DNS queries. + ```js + const dns = require('dns'); -Below is an example that resolves `'archive.org'` then reverse resolves the IP -addresses that are returned. - -```js -const dns = require('dns'); - -dns.resolve4('archive.org', (err, addresses) => { - if (err) throw err; - - console.log(`addresses: ${JSON.stringify(addresses)}`); - - addresses.forEach((a) => { - dns.reverse(a, (err, hostnames) => { - if (err) { - throw err; - } - console.log(`reverse for ${a}: ${JSON.stringify(hostnames)}`); + dns.lookup('iana.org', (err, address, family) => { + console.log('address: %j family: IPv%s', address, family); }); - }); -}); -``` + // address: "192.0.43.8" family: IPv4 + ``` + +2. Functions that connect to an actual DNS server to perform name resolution, + 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 + developers who do not want to use the underlying operating system's + facilities for name resolution, and instead want to _always_ perform DNS + queries. + + Below is an example that resolves `'archive.org'` then reverse resolves the + IP addresses that are returned. + + ```js + const dns = require('dns'); + + dns.resolve4('archive.org', (err, addresses) => { + if (err) throw err; + + console.log(`addresses: ${JSON.stringify(addresses)}`); + + addresses.forEach((a) => { + dns.reverse(a, (err, hostnames) => { + if (err) { + throw err; + } + console.log(`reverse for ${a}: ${JSON.stringify(hostnames)}`); + }); + }); + }); + ``` There are subtle consequences in choosing one over the other, please consult the [Implementation considerations section][] for more information. diff --git a/doc/guides/backporting-to-release-lines.md b/doc/guides/backporting-to-release-lines.md index 5b531639e77de5..ab3783672ea3f5 100644 --- a/doc/guides/backporting-to-release-lines.md +++ b/doc/guides/backporting-to-release-lines.md @@ -35,34 +35,34 @@ replace that with the staging branch for the targeted release line. 2. Make sure that the local staging branch is up to date with the remote 3. Create a new branch off of the staging branch -```shell -# Assuming your fork of Node.js is checked out in $NODE_DIR, -# the origin remote points to your fork, and the upstream remote points -# to git://github.com/nodejs/node -cd $NODE_DIR -# If v8.x-staging is checked out `pull` should be used instead of `fetch` -git fetch upstream v8.x-staging:v8.x-staging -f -# Assume we want to backport PR #10157 -git checkout -b backport-10157-to-v8.x v8.x-staging -# Ensure there are no test artifacts from previous builds -# Note that this command deletes all files and directories -# not under revision control below the ./test directory. -# It is optional and should be used with caution. -git clean -xfd ./test/ -``` + ```shell + # Assuming your fork of Node.js is checked out in $NODE_DIR, + # the origin remote points to your fork, and the upstream remote points + # to git://github.com/nodejs/node + cd $NODE_DIR + # If v8.x-staging is checked out `pull` should be used instead of `fetch` + git fetch upstream v8.x-staging:v8.x-staging -f + # Assume we want to backport PR #10157 + git checkout -b backport-10157-to-v8.x v8.x-staging + # Ensure there are no test artifacts from previous builds + # Note that this command deletes all files and directories + # not under revision control below the ./test directory. + # It is optional and should be used with caution. + git clean -xfd ./test/ + ``` 4. After creating the branch, apply the changes to the branch. The cherry-pick will likely fail due to conflicts. In that case, you will see something like this: -```shell -# Say the $SHA is 773cdc31ef -$ git cherry-pick $SHA # Use your commit hash -error: could not apply 773cdc3... -hint: after resolving the conflicts, mark the corrected paths -hint: with 'git add ' or 'git rm ' -hint: and commit the result with 'git commit' -``` + ```shell + # Say the $SHA is 773cdc31ef + $ git cherry-pick $SHA # Use your commit hash + error: could not apply 773cdc3... + hint: after resolving the conflicts, mark the corrected paths + hint: with 'git add ' or 'git rm ' + hint: and commit the result with 'git commit' + ``` 5. Make the required changes to remove the conflicts, add the files to the index using `git add`, and then commit the changes. That can be done with diff --git a/doc/guides/updating-root-certs.md b/doc/guides/updating-root-certs.md index 9eb07b912a31b1..41c83e5898bd10 100644 --- a/doc/guides/updating-root-certs.md +++ b/doc/guides/updating-root-certs.md @@ -20,106 +20,106 @@ the nodejs/node repository. 1. Find NSS metadata for update. -The latest released NSS version, release date, Firefox version, and Firefox -release date can be found in the [NSS release schedule][]. + The latest released NSS version, release date, Firefox version, and Firefox + release date can be found in the [NSS release schedule][]. -The tag to fetch `certdata.txt` from is found by looking for the release -version in the [tag list][]. + The tag to fetch `certdata.txt` from is found by looking for the release + version in the [tag list][]. 2. Update `certdata.txt` from the NSS release tag. -Update the tag in the commands below, and run: + Update the tag in the commands below, and run: -```shell -cd tools/ -./mk-ca-bundle.pl -v 2>_before -curl -O https://hg.mozilla.org/projects/nss/raw-file/NSS_3_41_RTM/lib/ckfw/builtins/certdata.txt -``` + ```shell + cd tools/ + ./mk-ca-bundle.pl -v 2>_before + curl -O https://hg.mozilla.org/projects/nss/raw-file/NSS_3_41_RTM/lib/ckfw/builtins/certdata.txt + ``` -The `_before` file will be used later. Verify that running `mk-ca-bundle` made -no changes to `src/node_root_certs.h`. If it did, something went wrong with the -previous update. Seek help! + The `_before` file will be used later. Verify that running `mk-ca-bundle` + made no changes to `src/node_root_certs.h`. If it did, something went wrong + with the previous update. Seek help! -Update metadata in the message below, and commit `certdata.txt`: + Update metadata in the message below, and commit `certdata.txt`: -```text -tools: update certdata.txt + ```text + tools: update certdata.txt -This is the certdata.txt[0] from NSS 3.41, released on 2018-12-03. + This is the certdata.txt[0] from NSS 3.41, released on 2018-12-03. -This is the version of NSS that will ship in Firefox 65 on -2018-12-11. + This is the version of NSS that will ship in Firefox 65 on + 2018-12-11. -[0] https://hg.mozilla.org/projects/nss/raw-file/NSS_3_41_RTM/lib/ckfw/builtins/certdata.txt -``` + [0] https://hg.mozilla.org/projects/nss/raw-file/NSS_3_41_RTM/lib/ckfw/builtins/certdata.txt + ``` 3. Update `node_root_certs.h` from `certdata.txt`. -Run the command below: - -```shell -./mk-ca-bundle.pl -v 2>_after -``` - -Confirm that `../src/node_root_certs.h` was updated. - -Determine what changes were made by diffing the before and after files: - -```shell -% diff _before _after -11d10 -< Parsing: Visa eCommerce Root -106d104 -< Parsing: TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı H5 -113,117d110 -< Parsing: Certplus Root CA G1 -< Parsing: Certplus Root CA G2 -< Parsing: OpenTrust Root CA G1 -< Parsing: OpenTrust Root CA G2 -< Parsing: OpenTrust Root CA G3 -134c127,136 -< Done (133 CA certs processed, 20 skipped). ---- -> Parsing: GlobalSign Root CA - R6 -> Parsing: OISTE WISeKey Global Root GC CA -> Parsing: GTS Root R1 -> Parsing: GTS Root R2 -> Parsing: GTS Root R3 -> Parsing: GTS Root R4 -> Parsing: UCA Global G2 Root -> Parsing: UCA Extended Validation Root -> Parsing: Certigna Root CA -> Done (135 CA certs processed, 16 skipped). -``` - -Use the diff to update the message below, and commit `src/node_root_certs.h`: - -```text -crypto: update root certificates - -Update the list of root certificates in src/node_root_certs.h with -tools/mk-ca-bundle.pl. - -Certificates added: -- GlobalSign Root CA - R6 -- OISTE WISeKey Global Root GC CA -- GTS Root R1 -- GTS Root R2 -- GTS Root R3 -- GTS Root R4 -- UCA Global G2 Root -- UCA Extended Validation Root -- Certigna Root CA - -Certificates removed: -- Visa eCommerce Root -- TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı H5 -- Certplus Root CA G1 -- Certplus Root CA G2 -- OpenTrust Root CA G1 -- OpenTrust Root CA G2 -- OpenTrust Root CA G3 -``` + Run the command below: + + ```shell + ./mk-ca-bundle.pl -v 2>_after + ``` + + Confirm that `../src/node_root_certs.h` was updated. + + Determine what changes were made by diffing the before and after files: + + ```shell + % diff _before _after + 11d10 + < Parsing: Visa eCommerce Root + 106d104 + < Parsing: TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı H5 + 113,117d110 + < Parsing: Certplus Root CA G1 + < Parsing: Certplus Root CA G2 + < Parsing: OpenTrust Root CA G1 + < Parsing: OpenTrust Root CA G2 + < Parsing: OpenTrust Root CA G3 + 134c127,136 + < Done (133 CA certs processed, 20 skipped). + --- + > Parsing: GlobalSign Root CA - R6 + > Parsing: OISTE WISeKey Global Root GC CA + > Parsing: GTS Root R1 + > Parsing: GTS Root R2 + > Parsing: GTS Root R3 + > Parsing: GTS Root R4 + > Parsing: UCA Global G2 Root + > Parsing: UCA Extended Validation Root + > Parsing: Certigna Root CA + > Done (135 CA certs processed, 16 skipped). + ``` + + Use the diff to update the message below, and commit `src/node_root_certs.h`: + + ```text + crypto: update root certificates + + Update the list of root certificates in src/node_root_certs.h with + tools/mk-ca-bundle.pl. + + Certificates added: + - GlobalSign Root CA - R6 + - OISTE WISeKey Global Root GC CA + - GTS Root R1 + - GTS Root R2 + - GTS Root R3 + - GTS Root R4 + - UCA Global G2 Root + - UCA Extended Validation Root + - Certigna Root CA + + Certificates removed: + - Visa eCommerce Root + - TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı H5 + - Certplus Root CA G1 + - Certplus Root CA G2 + - OpenTrust Root CA G1 + - OpenTrust Root CA G2 + - OpenTrust Root CA G3 + ``` [NSS release schedule]: https://wiki.mozilla.org/NSS:Release_Versions [tag list]: https://hg.mozilla.org/projects/nss/tags