Skip to content

Commit cc22d35

Browse files
committed
doc: clarify the review and landing process
- Explains what "nits" stand for - Explains commit squashing - Mentions the CI run - Mentions the mandatory 48/72 hours wait - Mention GitHub's PR review feature - Fix indentation
1 parent d8c7534 commit cc22d35

File tree

1 file changed

+45
-7
lines changed

1 file changed

+45
-7
lines changed

CONTRIBUTING.md

+45-7
Original file line numberDiff line numberDiff line change
@@ -237,6 +237,20 @@ $ git commit --amend
237237
$ git push --force-with-lease origin my-branch
238238
```
239239

240+
When the commits in your Pull Request get landed, they will be squashed into
241+
one commit per logical change, with metadata added to the commit message
242+
(including links to the Pull Request, links to relevant issues,
243+
and the names of the reviewers). The squashing will be done by someone
244+
who has the commit access to the repository. The commit history of
245+
your Pull Request, however, will stay intact on the Pull Request
246+
page (as long as you don't delete your fork branch, at which point
247+
it disappears).
248+
249+
Notes: For the size of "one logical change",
250+
[0b5191f](https://github.com/nodejs/node/commit/0b5191f15d0f311c804d542b67e2e922d98834f8)
251+
can be a good example. It touches the implementation, the documentation,
252+
and the tests, but is still one logical change.
253+
240254
**Important:** The `git push --force-with-lease` command is one of the few ways
241255
to delete history in git. Before you use it, make sure you understand the risks.
242256
If in doubt, you can always ask for guidance in the Pull Request or on
@@ -245,16 +259,40 @@ If in doubt, you can always ask for guidance in the Pull Request or on
245259
Feel free to post a comment in the Pull Request to ping reviewers if you are
246260
awaiting an answer on something.
247261

262+
Notes: if the reviewer mentions *nits* in their comments, that means
263+
"requests for changes that are not essential". Usually these nits are
264+
related to coding styles or typos. It's always a good idea to pay
265+
attention to the detail!
248266

249267
### Step 8: Landing
250268

251-
Once your Pull Request has been reviewed and approved by at least one Node.js
252-
Collaborators (often by saying LGTM, or Looks Good To Me), and as long as
253-
there is consensus (no objections from a Collaborator), a
254-
Collaborator can merge the Pull Request . GitHub often shows the Pull Request as
255-
`Closed` at this point, but don't worry. If you look at the branch you raised
256-
your Pull Request against (probably `master`), you should see a commit with
257-
your name on it. Congratulations and thanks for your contribution!
269+
In order to get landed, a Pull Request needs to be reviewed and approved by
270+
at least one Node.js Collaborator (either by saying LGTM,
271+
which stands for "Looks Good To Me", or by using GitHub's Approve button).
272+
GitHub's Pull Request review feature is used in this process. For more
273+
information, check out [the video tutorial](https://www.youtube.com/watch?v=HW0RPaJqm4g)
274+
or [the official documentation](https://help.github.com/articles/reviewing-changes-in-pull-requests/).
275+
276+
Notes: After you push new changes to your branch, you need to get the
277+
approval for these new changes again, even if GitHub shows "Approved"
278+
because the reviwers have hit the buttons before.
279+
280+
If this Pull Request touches more than the documentation, then it also
281+
needs an all-green CI (Continuous Integration) test run. Only a
282+
Collaborator can request a CI run. Usually one of them will do it
283+
for you as approvals for the Pull Request come in.
284+
If not, you can ask a Collaborator to request a CI run.
285+
286+
After your Pull Request has been approved by one or more Node.js
287+
Collaborators and has passed the CI, as long as there is consensus
288+
(no objections from a Collaborator), it can be merged by a Collaborator.
289+
But, if there are non-trivial changes in this Pull Request, it still
290+
needs to wait for at least another 48 hours (72 hours on a weekend).
291+
292+
GitHub often shows the Pull Request as `Closed` at this point,
293+
but don't worry. If you look at the branch you raised your Pull Request
294+
against (probably `master`), you should see a commit with
295+
your name on it. Congratulations and thanks for your contribution!
258296

259297
<a id="developers-certificate-of-origin"></a>
260298
## Developer's Certificate of Origin 1.1

0 commit comments

Comments
 (0)