[2023-04-11]: Comment on files in a pull request - [GA] #9856 (#36146)

Co-authored-by: Jules <19994093+jules-p@users.noreply.github.com>

content/get-started/quickstart/github-flow.md

@@ -77,10 +77,11 @@ If your repository has checks configured to run on pull requests, you will see a
 
 ### Address review comments
 
-Reviewers should leave questions, comments, and suggestions. Reviewers can comment on the whole pull request or add comments to specific lines. You and reviewers can insert images or code suggestions to clarify comments. For more information, see "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests)."
+Reviewers should leave questions, comments, and suggestions. Reviewers can comment on the whole pull request or add comments to specific lines{% ifversion pull-request-comment-on-file %} or files{% endif %}. You and reviewers can insert images or code suggestions to clarify comments. For more information, see "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests)."
 
 You can continue to commit and push changes in response to the reviews. Your pull request will update automatically.
 
+
 ### Merge your pull request
 
 Once your pull request is approved, merge your pull request. This will automatically merge your branch so that your changes appear on the default branch. {% data variables.product.prodname_dotcom %} retains the history of comments and commits in the pull request to help future contributors understand your changes. For more information, see "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request)."

content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews.md

@@ -30,7 +30,7 @@ You can comment on a pull request, approve the changes, or request improvements
 {% data reusables.repositories.sidebar-pr %}
 {% data reusables.repositories.choose-pr-review %}
 {% data reusables.repositories.changed-files %}
-4. Review the changes in the pull request, and optionally, [comment on specific lines](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request#starting-a-review).
+4. Review the changes in the pull request, and optionally, comment on specific lines{% ifversion pull-request-comment-on-file %} or files{% endif %}. For more information, see "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request#starting-a-review)."
 {% data reusables.repositories.review-changes %}
 {% data reusables.repositories.review-summary-comment %}
 7. Select **Approve** to approve merging the changes proposed in the pull request.

content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request.md

@@ -22,9 +22,9 @@ shortTitle: Comment on a PR
 
 You can comment on a pull request's **Conversation** tab to leave general comments, questions, or props. You can also suggest changes that the author of the pull request can apply directly from your comment.
 
-You can also comment on specific sections of a file on a pull request's **Files changed** tab in the form of individual line comments or as part of a [pull request review](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews). Adding line comments is a great way to discuss questions about implementation or provide feedback to the author.
+You can also comment on specific {% ifversion pull-request-comment-on-file %}files or {% endif %}sections of a file in a pull request's **Files changed** tab in the form of individual line {% ifversion pull-request-comment-on-file %}or file {% endif %}comments, or as part of a pull request review. Adding line {% ifversion pull-request-comment-on-file %}or file {% endif %}comments is a great way to discuss questions about implementation or provide feedback to the author. For more information about pull request reviews, see "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews)."
 
-For more information on adding line comments to a pull request review, see "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request)."
+For more information on adding line {% ifversion pull-request-comment-on-file %}or file {% endif %}comments to a pull request review, see "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request)."
 
 {% note %}
 
@@ -32,7 +32,7 @@ For more information on adding line comments to a pull request review, see "[AUT
 
 {% endnote %}
 
-To reply to an existing line comment, you'll need to navigate to the comment on either the **Conversation** tab or **Files changed** tab and add an additional line comment below it.
+To reply to an existing line {% ifversion pull-request-comment-on-file %}or file {% endif %}comment, you'll need to navigate to the comment on either the **Conversation** tab or **Files changed** tab and add an additional comment below it.
 
 {% tip %}
 
@@ -42,15 +42,17 @@ To reply to an existing line comment, you'll need to navigate to the comment on
 
 {% endtip %}
 
-## Adding line comments to a pull request
+## Adding comments to a pull request
 
 {% data reusables.repositories.sidebar-pr %}
-2. In the list of pull requests, click the pull request where you'd like to leave line comments.
+1. In the list of pull requests, click the pull request where you'd like to leave line comments.
 {% data reusables.repositories.changed-files %}
 {% data reusables.repositories.start-line-comment %}
 {% data reusables.repositories.type-line-comment %}
 {% data reusables.repositories.suggest-changes %}
-5. When you're done, click **Add single comment**.
+{% ifversion pull-request-comment-on-file %}
+{% data reusables.repositories.start-file-comment %}{% endif %}
+1. When you're done, click **Add single comment**.
 
 Anyone watching the pull request or repository will receive a notification of your comment.
 

content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request.md

@@ -37,6 +37,8 @@ You can change the format of the diff view in this tab by clicking {% octicon "g
 {% data reusables.repositories.start-line-comment %}
 {% data reusables.repositories.type-line-comment %}
 {% data reusables.repositories.suggest-changes %}
+{% ifversion pull-request-comment-on-file %}
+{% data reusables.repositories.start-file-comment %}{% endif %}
 1. When you're done, click **Start a review**. If you have already started a review, you can click **Add review comment**.
 
 Before you submit your review, your line comments are _pending_ and only visible to you. You can edit pending comments anytime before you submit your review. To cancel a pending review, including all of its pending comments, click **Review changes** above the changed code, then click **Cancel review**.

data/features/pull-request-comment-on-file.yml

@@ -0,0 +1,6 @@
+# Issue 9856 - Comment on a file in pull requests (an image or source file)
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>=3.9'
+  ghae: '>= 3.9'

data/reusables/repositories/start-file-comment.md

@@ -0,0 +1,3 @@
+1. To comment directly on a file, to the right of the file, click {% octicon "comment" aria-label="The comment icon" %} and type your comment.
+
+   ![Screenshot of an image file on the "Files changed" page of a pull request. To the right of the image file, a comment icon is highlighted with an orange outline.](/assets/images/help/pull_requests/pull-request-comment-on-file.png)