docs: Guideline for PR comments & reviews (#3001)

Signed-off-by: redoomed1 <redoomed1@privacyguides.org>
Signed-off-by: fria <fria@privacyguides.org>
Signed-off-by: Daniel Gray <dngray@privacyguides.org>

docs/meta/pr-comments.md

@@ -0,0 +1,43 @@
+---
+title: Commenting on PRs
+description: A guide on participating in Pull Request discussions.
+---
+Please refrain from using the general **Add a comment** box in GitHub PRs when leaving a comment or performing a review.
+
+![Do not use the general "Add a comment" box in GitHub](../assets/img/meta/pr-avoid-general-comments.png)
+
+Comments that are left like this are not *threaded*, which makes it difficult to keep track of multiple conversations.
+
+Comments that are instead left in the manner described below will have a built-in reply box to keep conversations in a single thread. These comments can also be marked as resolved afterwards, so that discussion can be tracked more easily.
+
+![A screenshot of a comment in GitHub which has a built-in "reply" box, highlighted in orange.](../assets/img/meta/pr-threaded-comment.png)
+
+## Commenting
+
+To start a threaded comment, you should leave all comments under the :octicons-file-diff-16: **Files changed** tab in a PR.
+
+![Screenshot of the tabs for a pull request. The "Files changed" tab is outlined in dark orange.](https://docs.github.com/assets/cb-23571/mw-1440/images/help/pull_requests/pull-request-tabs-changed-files.webp)
+
+To leave a *general* comment on a PR, click the :octicons-comment-16: comment icon to the right of a file:
+
+![Screenshot of an image file on the "Files changed" page of a pull request. To the right of the file, a comment icon is outlined in orange.](https://docs.github.com/assets/cb-73771/mw-1440/images/help/pull_requests/pull-request-comment-on-file.webp)
+
+If the PR has multiple files changed, comment on the primary or most relevant file changed, or comment on the first file if you can't decide.
+
+To leave a comment *on a specific line* of a PR, hover over the line where you'd like to add a comment, and click the blue comment icon:
+
+![Screenshot of a diff in a pull request. Next to a line number, a blue plus icon is highlighted with an orange outline.](https://docs.github.com/assets/cb-44227/mw-1440/images/help/commits/hover-comment-icon.webp)
+
+(Optionally, you can add a comment on multiple lines. You can click the line number of the first line you want to comment on and drag down to select a range of lines, then click the blue comment icon on the last line you want to comment on. Alternatively, you can click the blue comment icon next to the first line you want to comment on, then drag down to the last line you want to comment on.)
+
+Then, type your comment and click **Add single comment**.
+
+## Reviewing
+
+When performing a review, follow the same steps as above, but click **Start a review** (and subsequently, **Add a review comment**) instead of **Add single comment**.
+
+Then, click the green **Finish your review** button at the top of the page.
+
+Do not leave any discussion comments in the *Leave a comment* box in the review finalization pop-up. You can leave it blank, or leave a short note if it will not require any follow-up. To comment on something that will require further discussion, add a comment on a file as described above instead.
+
+Then, click **Submit review**.

mkdocs.yml

@@ -474,6 +474,7 @@ nav:
               - "meta/uploading-images.md"
               - "meta/git-recommendations.md"
               - "meta/commit-messages.md"
+              - "meta/pr-comments.md"
 
 validation:
   nav: