Update PR review auto-comments (#54362)

heiskr · web-flow · commit c1db7a304337 · 2025-02-11T21:05:04.000Z
diff --git a/.github/workflows/comment-code-changes.yml b/.github/workflows/comment-code-changes.yml
@@ -1,7 +1,7 @@
 name: Code changes comment
 
-# **What it does**: When a PR is opened in docs-internal or docs containing code, it comments with instructions on how to deploy and preview the changes.
-# **Why we have it**: To help Docs contributors understand how to preview their changes.
+# **What it does**: When a PR is opened in docs-internal or docs containing code, it comments with instructions on how to deploy and review the changes.
+# **Why we have it**: To help Docs contributors understand how to review their changes.
 # **Who does it impact**: docs-internal and docs maintainers and contributors
 
 on:
@@ -49,22 +49,29 @@ jobs:
         run: |
           if [[ "${{ github.repository }}" == "github/docs" ]]; then
             COMMENT_BODY="<!-- CODE_CHANGES_COMMENT -->
-            ## 🚀 Manual Deployment Required
+            ### 👓 How to review these changes
 
-            It looks like this pull request contains code changes. To preview these changes, an internal Hubber will need to manually deploy the changes to one of our staging servers.
+            Thank you for your contribution. To review these changes, you can:
 
-            Thank you for your contribution!"
+            1. [Spin up a codespace](https://docs.github.com/en/contributing/setting-up-your-environment-to-work-on-github-docs/working-on-github-docs-in-a-codespace)
+            1. [Set up a local development environment](https://docs.github.com/en/contributing/setting-up-your-environment-to-work-on-github-docs/creating-a-local-environment#setting-up-your-local-environment)
+
+            This pull request contains code changes, so we will not generate a table of review links. A Hubber will need to deploy your changes internally to review.
+
+            🤖 This comment is automatically generated."
           else
             COMMENT_BODY="<!-- CODE_CHANGES_COMMENT -->
-            ## 🚀 Manual Deployment Required
+            ### 👓 How to review these changes
 
-            It looks like this pull request contains code changes. To preview these changes, please do one of:
+            Thank you for your contribution. To review these changes, you can:
 
-            1. [Set up a local development environment](https://github.com/github/docs/blob/main/contributing/development.md).
-            1. [Spin up a codespace to review](https://github.com/github/docs-engineering/blob/main/docs/team-practices/use-a-codespace-to-review.md).
+            1. [Spin up a codespace](https://github.com/github/docs-team/blob/main/contributing-to-docs/use-a-codespace-to-review.md).
+            1. [Set up a local development environment](https://docs.github.com/en/contributing/setting-up-your-environment-to-work-on-github-docs/creating-a-local-environment#setting-up-your-local-environment).
             1. Message \`#docs-engineering\` on Slack for a staging server.
 
-            Thank you for your contribution!"
+            This pull request contains code changes, so we will not generate a table of review links.
+
+            🤖 This comment is automatically generated."
           fi
 
           gh pr comment ${{ github.event.pull_request.number }} --body "$COMMENT_BODY"
diff --git a/.github/workflows/comment-content-changes-table.yml b/.github/workflows/comment-content-changes-table.yml
@@ -1,6 +1,6 @@
 name: Content Changes Table Comment
 
-# **What it does**: When a PR is opened in docs-internal or docs, it adds the staging preview and live article links in a Content Directory Changes table in a comment
+# **What it does**: When a PR is opened in docs-internal or docs, it adds the staging review and live article links in a Content Directory Changes table in a comment
 # **Why we have it**: To help Docs Content team members and contributors automatically have their staging/live article links added to the table
 # **Who does it impact**: docs-internal/docs maintainers and contributors
 
@@ -89,22 +89,30 @@ jobs:
           issue-number: ${{ github.event.pull_request.number || inputs.PR_NUMBER }}
           body: |
             <!-- MODIFIED_CONTENT_LINKING_COMMENT -->
-            ## 👓 Previews for changed content
-            **This comment is 🤖 automatically generated and will be overwritten every time changes are committed to this branch.**
+            ### 👓 How to review these changes
 
-            The table contains an overview of files in the `content` directory that have been changed in this pull request. It's provided to make it easy to review your changes on the review server. Please note that changes to the `data` directory will not show up in this table.
+            Thank you for your contribution. To review these changes, you can:
 
-            :bangbang: You can also preview changes [using Codespaces](https://github.com/github/docs-engineering/blob/main/docs/team-practices/use-a-codespace-to-review.md) or by [spinning up a local environment](https://docs.github.com/en/contributing/setting-up-your-environment-to-work-on-github-docs/creating-a-local-environment). Please continue to [let us know](https://github.com/github/docs-team/discussions/4889) if you have trouble with the review server and use one of those options to preview your changes.
+            1. [Spin up a codespace](https://github.com/github/docs-team/blob/main/contributing-to-docs/use-a-codespace-to-review.md).
+            1. [Set up a local development environment](https://docs.github.com/en/contributing/setting-up-your-environment-to-work-on-github-docs/creating-a-local-environment#setting-up-your-local-environment).
+            1. Message \`#docs-engineering\` on Slack for a staging server.
 
-            ---
+            <details><summary>Table of review links</summary>
+
+            > [!WARNING]
+            > Our review server is experiencing latency issues.
+
+            The table shows the files in the `content` directory that were changed in this pull request. This helps you review your changes on the review server. Changes to the `data` directory are not included in this table. If you have issues with the review server, please [let us know](https://github.com/github/docs-team/discussions/4889) and use one of the other options to review your changes.
 
-            ### Content directory changes
-            _You may find it useful to copy this table into the pull request summary. There you can edit it to share links to important articles or changes and to give a high-level overview of how the changes in your pull request support the overall goals of the pull request._
             ${{ steps.changes.outputs.changesTable }}
 
             ---
             Key: **fpt**: Free, Pro, Team; **ghec**: GitHub Enterprise Cloud; **ghes**: GitHub Enterprise Server
             _This table is posted from the [${{ github.workflow }}](https://github.com/${{ github.repository }}/blob/${{ github.sha }}/.github/workflows/comment-content-changes-table.yml) workflow._
+
+            </details>
+
+            🤖 This comment is automatically generated.
           edit-mode: replace
 
       - name: Update comment on docs public
@@ -115,20 +123,29 @@ jobs:
           issue-number: ${{ github.event.pull_request.number || inputs.PR_NUMBER }}
           body: |
             <!-- MODIFIED_CONTENT_LINKING_COMMENT -->
-            ## 👓 Previews for changed content
-            **This comment is 🤖 automatically generated and will be overwritten every time changes are committed to this branch.**
+            ### 👓 How to review these changes
 
-            The table contains an overview of files in the `content` directory that have been changed in this pull request. It's provided to make it easy to review your changes on the review server. Please note that changes to the `data` directory will not show up in this table.
+            Thank you for your contribution. To review these changes, you can:
 
-            :bangbang: You can also preview changes [using Codespaces](https://docs.github.com/en/contributing/setting-up-your-environment-to-work-on-github-docs/working-on-github-docs-in-a-codespace) or by [spinning up a local environment](https://docs.github.com/en/contributing/setting-up-your-environment-to-work-on-github-docs/creating-a-local-environment). If you have trouble with the review server, use one of those options to preview your changes.
+            1. [Spin up a codespace](https://docs.github.com/en/contributing/setting-up-your-environment-to-work-on-github-docs/working-on-github-docs-in-a-codespace)
+            1. [Set up a local development environment](https://docs.github.com/en/contributing/setting-up-your-environment-to-work-on-github-docs/creating-a-local-environment#setting-up-your-local-environment)
 
-            ---
+            A Hubber will need to deploy your changes internally to review.
+
+            <details><summary>Table of review links</summary>
+
+            > [!WARNING]
+            > Our review server is experiencing latency issues.
+
+            The table shows the files in the `content` directory that were changed in this pull request. This helps you review your changes on the review server. Changes to the `data` directory are not included in this table.
 
-            ### Content directory changes
-            _You may find it useful to copy this table into the pull request summary. There you can edit it to share links to important articles or changes and to give a high-level overview of how the changes in your pull request support the overall goals of the pull request._
             ${{ steps.changes.outputs.changesTable }}
 
             ---
             Key: **fpt**: Free, Pro, Team; **ghec**: GitHub Enterprise Cloud; **ghes**: GitHub Enterprise Server
             _This table is posted from the [${{ github.workflow }}](https://github.com/${{ github.repository }}/blob/${{ github.sha }}/.github/workflows/comment-content-changes-table.yml) workflow._
+
+            </details>
+
+            🤖 This comment is automatically generated.
           edit-mode: replace
diff --git a/.github/workflows/keep-caches-warm.yml b/.github/workflows/keep-caches-warm.yml
@@ -7,7 +7,7 @@ name: Keep caches warm
 #   actions cache is warmed up with data available during deployment
 #   actions. When you use actions/cache within a run on `main`
 #   what gets saved can be used by other pull requests. But it's
-#   also so that when we make preview or production deployments,
+#   also so that when we make production deployments,
 #   we can just rely on the cache to already be warmed up.
 # **Why we have it**:
 #   A PR workflow that depends on caching can't reuse a
diff --git a/src/workflows/content-changes-table-comment-cli.ts b/src/workflows/content-changes-table-comment-cli.ts
@@ -13,7 +13,7 @@
 // To try it you need to generate a local `GITHUB_TOKEN` that has read-access
 // "content" and "pull requests" on the repo.
 // You also need to set an APP_URL which can be the domain of the
-// preview environment or just the production domain. Example:
+// review environment or just the production domain. Example:
 //
 //
 //    export GITHUB_TOKEN=github_pat_11AAAG.....
diff --git a/src/workflows/content-changes-table-comment.ts b/src/workflows/content-changes-table-comment.ts
@@ -196,7 +196,7 @@ async function main(
     return ''
   }
 
-  const headings = ['Source', 'Preview', 'Production', 'What Changed']
+  const headings = ['Source', 'Review', 'Production', 'What Changed']
   const markdownTableHead = [
     `| ${headings.map((heading) => `**${heading}**`).join(' | ')} |`,
     `| ${headings.map(() => ':---').join(' | ')} |`,
@@ -241,7 +241,7 @@ function makeRow({
   fromReusable?: boolean
 }) {
   let contentCell = ''
-  let previewCell = ''
+  let reviewCell = ''
   let prodCell = ''
 
   if (file.status === 'added') contentCell = 'New file: '
@@ -269,25 +269,25 @@ function makeRow({
         if (versions.toString() === nonEnterpriseDefaultVersion) {
           // omit version from fpt url
 
-          previewCell += `[${plan}](${APP_URL}/${fileUrl}${queryParams})<br>`
+          reviewCell += `[${plan}](${APP_URL}/${fileUrl}${queryParams})<br>`
           prodCell += `[${plan}](${PROD_URL}/${fileUrl})<br>`
         } else {
           // for non-versioned releases (ghec) use full url
 
-          previewCell += `[${plan}](${APP_URL}/${versions}/${fileUrl}${queryParams})<br>`
+          reviewCell += `[${plan}](${APP_URL}/${versions}/${fileUrl}${queryParams})<br>`
           prodCell += `[${plan}](${PROD_URL}/${versions}/${fileUrl})<br>`
         }
       } else if (versions.length) {
         // for ghes releases, link each version
 
-        previewCell += `${plan}@ `
+        reviewCell += `${plan}@ `
         prodCell += `${plan}@ `
 
         versions.forEach((version) => {
-          previewCell += `[${version.split('@')[1]}](${APP_URL}/${version}/${fileUrl}${queryParams}) `
+          reviewCell += `[${version.split('@')[1]}](${APP_URL}/${version}/${fileUrl}${queryParams}) `
           prodCell += `[${version.split('@')[1]}](${PROD_URL}/${version}/${fileUrl}) `
         })
-        previewCell += '<br>'
+        reviewCell += '<br>'
         prodCell += '<br>'
       }
     }
@@ -299,14 +299,14 @@ function makeRow({
   let note = ''
   if (file.status === 'removed') {
     note = 'removed'
-    // If the file was removed, the `previewCell` no longer makes sense
+    // If the file was removed, the `reviewCell` no longer makes sense
     // since it was based on looking at the base sha.
-    previewCell = 'n/a'
+    reviewCell = 'n/a'
   } else if (fromReusable) {
     note += 'from reusable'
   }
 
-  return `| ${contentCell} | ${previewCell} | ${prodCell} | ${note} |`
+  return `| ${contentCell} | ${reviewCell} | ${prodCell} | ${note} |`
 }
 
 function getAllContentFiles(): Map<string, string> {
