doc: explains why Reviewed-By is added in PRs

Adds verbose reasons to the documentation on why the Reviewed-By metadata on a pull request is important. This was loosely mentioned as an issue in the referenced issue below, and answered by @addaleax. Ref: #8893 change wording on documentation update Changes the initial commit to the recommended, and more accurate wording. Removed time qualifiers on documentation for git merge removes the ugly wording add a new reason why autosquashing is prohibited
nodejs · Oct 13, 2016 · 177d880 · 177d880
1 parent d42d56f
commit 177d880
Show file tree

Hide file tree

Showing 2 changed files with 6 additions and 3 deletions.
diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md
@@ -101,6 +101,8 @@ information regarding the change process:
 
 - A `Reviewed-By: Name <email>` line for yourself and any
   other Collaborators who have reviewed the change.
+  - Useful for @mentions / contact list if something goes wrong in the PR.
+  - Protects against the assumption that GitHub will be around forever.
 - A `PR-URL:` line that references the *full* GitHub URL of the original
   pull request being merged so it's easy to trace a commit back to the
   conversation that led up to that change.

diff --git a/doc/onboarding.md b/doc/onboarding.md
@@ -167,10 +167,11 @@ onboarding session.
 * Please never use GitHub's green ["Merge Pull Request"](https://help.github.com/articles/merging-a-pull-request/#merging-a-pull-request-using-the-github-web-interface) button.
   * If you do, please force-push removing the merge.
   * Reasons for not using the web interface button:
-    * The old merge method will write an ugly commit message.
-    * The old rebase & merge method adds metadata to the commit title.
-    * The latest rebase method changes the author.
+    * The merge method will add an unnecessary merge commit.
+    * The rebase & merge method adds metadata to the commit title.
+    * The rebase method changes the author.
     * The squash & merge method has been known to add metadata to the commit title.
+    * If more than one author has contributed to the PR, only the latest author will be considered during the squashing.
 
 
 Update your `master` branch (or whichever branch you are landing on, almost always `master`)