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