From 52dd524e0f4c4051389227392cb5a6d3ff63953f Mon Sep 17 00:00:00 2001
From: Rich Trott <rtrott@gmail.com>
Date: Fri, 25 Sep 2020 07:10:39 -0700
Subject: [PATCH] doc: revise introductory child_process text
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This consolidates information about Windows environment variables and
has a few other smaller improvements (punctuation, present tense, etc.).

Co-authored-by: Shelley Vohr <codebytere@gmail.com>

PR-URL: https://github.com/nodejs/node/pull/35296
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
---
 doc/api/child_process.md         | 31 +++++++++++++++----------------
 doc/guides/collaborator-guide.md |  8 ++++++++
 2 files changed, 23 insertions(+), 16 deletions(-)

diff --git a/doc/api/child_process.md b/doc/api/child_process.md
index 235a2a80e71e2a..d55d7bbc75c22c 100644
--- a/doc/api/child_process.md
+++ b/doc/api/child_process.md
@@ -6,7 +6,7 @@
 
 <!-- source_link=lib/child_process.js -->
 
-The `child_process` module provides the ability to spawn child processes in
+The `child_process` module provides the ability to spawn subprocesses in
 a manner that is similar, but not identical, to popen(3). This capability
 is primarily provided by the [`child_process.spawn()`][] function:
 
@@ -28,24 +28,23 @@ ls.on('close', (code) => {
 ```
 
 By default, pipes for `stdin`, `stdout`, and `stderr` are established between
-the parent Node.js process and the spawned child. These pipes have
-limited (and platform-specific) capacity. If the child process writes to
-stdout in excess of that limit without the output being captured, the child
-process will block waiting for the pipe buffer to accept more data. This is
+the parent Node.js process and the spawned subprocess. These pipes have
+limited (and platform-specific) capacity. If the subprocess writes to
+stdout in excess of that limit without the output being captured, the
+subprocess blocks waiting for the pipe buffer to accept more data. This is
 identical to the behavior of pipes in the shell. Use the `{ stdio: 'ignore' }`
 option if the output will not be consumed.
 
-The command lookup will be performed using `options.env.PATH` environment
-variable if passed in `options` object, otherwise `process.env.PATH` will be
-used. To account for the fact that Windows environment variables are
-case-insensitive Node.js will lexicographically sort all `env` keys and choose
-the first one case-insensitively matching `PATH` to perform command lookup.
-This may lead to issues on Windows when passing objects to `env` option that
-have multiple variants of `PATH` variable.
-
-On Windows Node.js will sanitize the `env` by removing case-insensitive
-duplicates. Only first (in lexicographic order) entry will be passed to the
-child process.
+The command lookup is performed using the `options.env.PATH` environment
+variable if it is in the `options` object. Otherwise, `process.env.PATH` is
+used.
+
+On Windows, environment variables are case-insensitive. Node.js
+lexicographically sorts the `env` keys and uses the first one that
+case-insensitively matches. Only first (in lexicographic order) entry will be
+passed to the subprocess. This may lead to issues on Windows when passing
+objects to `env` option that have multiple variants of the same key, such as
+`PATH` and `Path`.
 
 The [`child_process.spawn()`][] method spawns the child process asynchronously,
 without blocking the Node.js event loop. The [`child_process.spawnSync()`][]
diff --git a/doc/guides/collaborator-guide.md b/doc/guides/collaborator-guide.md
index 6f408783449ae0..9c760530d542fc 100644
--- a/doc/guides/collaborator-guide.md
+++ b/doc/guides/collaborator-guide.md
@@ -469,6 +469,12 @@ code. If you wish to create the token yourself in advance, see
 
 ### Technical HOWTO
 
+Infrequently, it is necessary to manually perform the steps required to land a
+pull request rather than rely on `git-node`.
+
+<details>
+<summary>Manual landing steps</summary>
+
 Clear any `am`/`rebase` that might already be underway:
 
 ```text
@@ -626,6 +632,8 @@ your pull request shows the purple merged status,
 add the "Landed in \<commit hash>..\<commit hash>" comment if you added
 more than one commit.
 
+</details>
+
 ### Troubleshooting
 
 Sometimes, when running `git push upstream master`, you might get an error