Merge pull request #46164 from github/repo-sync

Repo sync

Author: docs-bot

.github/workflows/all-documents.yml

@@ -1,8 +1,6 @@
 name: All documents script
 
-# **What it does**: Verifies that the all-documents script works.
-# **Why we have it**: Code quality and sustainability.
-# **Who does it impact**: docs-engineering
+# Catches all-documents crashes. This workflow has no output assertions.
 
 on:
   pull_request:
@@ -38,5 +36,3 @@ jobs:
           echo ""
           echo "Look at the first 50 lines of the file..."
           cat all-documents.json | jq | head -n 50
-
-          # We're essentially expecting it to not crash and fail.

.github/workflows/article-api-docs.yml

@@ -1,16 +1,13 @@
 name: 'Check article-api docs'
 
-# **What it does**: Makes sure changes to the article api are documented.
-# **Why we have it**: So what's documented doesn't fall behind
-# **Who does it impact**: Docs engineering, CGS team
+# Keeps generated article API docs from falling behind middleware changes.
 
 on:
   workflow_dispatch:
   pull_request:
     paths:
       - 'src/article-api/middleware/article.ts'
       - 'src/article-api/middleware/pagelist.ts'
-      # Self-test
       - .github/workflows/article-api-docs.yml
 
 permissions:
@@ -34,8 +31,6 @@ jobs:
           if [ -n "$(git status --porcelain)" ]; then
             git status
             git diff
-
-            # Some whitespace for the sake of the message below
             echo ""
             echo ""
 

.github/workflows/auto-add-ready-for-doc-review.yml

@@ -1,8 +1,6 @@
 name: Auto-add ready-for-doc-review label
 
-# **What it does**: Automatically adds the "ready-for-doc-review" label to DIY docs PRs that contain content or data changes when they are opened in a non-draft state or converted from draft to ready for review.
-# **Why we have it**: To ensure DIY docs PRs are automatically added to the docs-content review board without requiring manual labeling.
-# **Who does it impact**: Contributors making content changes and docs-content reviewers.
+# Sends DIY content changes to the docs-content review board without manual labeling.
 
 on:
   pull_request:
@@ -34,8 +32,7 @@ jobs:
           github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
             try {
-              // Team is addressed by numeric ID (org github = 9919, team docs = 325922)
-              // because IDs survive team renames and slugs do not.
+              // 9919 is the github org and 325922 the docs team; numeric IDs survive renames.
               await github.request('GET /organizations/{org_id}/team/{team_id}/memberships/{username}', {
                 org_id: 9919,
                 team_id: 325922,

.github/workflows/auto-close-dependencies.yml

@@ -1,10 +1,6 @@
 name: Auto Close Open Source Dependency Updates
 
-# **What it does**:
-#  - close-external: Automatically close dependabot's pull requests in the open-source repository.
-# **Why we have it**:
-#  - close-external: To avoid duplicating updates against the internal repository.
-# **Who does it impact**: It helps docs engineering focus on higher value work.
+# Closes Dependabot dependency updates in github/docs because the internal repo owns them.
 
 on:
   pull_request:
@@ -48,7 +44,7 @@ jobs:
         run: |
           gh pr comment "$PR_URL" --body "This dependency update will be handled internally by our engineering team."
 
-      # Because we get far too much spam ;_;
+      # Lock conversations to stop repeated dependency-update comments.
       - name: Lock conversations
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
         env:

.github/workflows/benchmark-pages.yml

@@ -1,13 +1,11 @@
 name: 'Weekly page benchmark'
 
-# **What it does**: Benchmarks all pages via the article API, flags errors and slow pages
-# **Why we have it**: Catch perf regressions and broken pages before users hit them
-# **Who does it impact**: Docs engineering
+# Catches slow or broken article API pages before users hit them.
 
 on:
   workflow_dispatch:
   schedule:
-    - cron: '20 16 * * 1' # Every Monday at 16:20 UTC / 8:20 PST
+    - cron: '20 16 * * 1' # Mondays at 16:20 UTC.
 
 permissions:
   contents: read

.github/workflows/changelog-agent.yml

@@ -1,11 +1,7 @@
 name: Changelog agent — draft entry when a qualified PR merges
 
-# **What it does**: When a PR merges that closes a docs-content issue with a
-#   parent issue, uses an LLM to draft a changelog entry, opens a PR in
-#   github/docs-content, and DMs the author in Slack for review.
-# **Why we have it**: Automates the changelog drafting process so authors
-#   don't have to remember to write a changelog entry manually.
-# **Who does it impact**: docs-content team members.
+# Drafts internal changelog entries for merged PRs that close a docs-content child issue.
+# Authors review generated PRs before publication.
 
 on:
   pull_request:
@@ -81,7 +77,6 @@ jobs:
           script: |
             const author = '${{ steps.resolve_pr.outputs.pr_author }}';
 
-            // Fetch github-to-slack.json from docs-content via API
             let mapping = {};
             try {
               const { data } = await github.rest.repos.getContent({
@@ -96,7 +91,6 @@ jobs:
               return;
             }
 
-            // Remove non-user keys (like _comment)
             const teamMembers = Object.keys(mapping).filter(k => !k.startsWith('_'));
 
             if (!teamMembers.includes(author)) {
@@ -119,8 +113,7 @@ jobs:
           script: |
             const body = process.env.PR_BODY || '';
 
-            // Match closing keywords followed by docs-content issue references.
-            // Supports: closes github/docs-content#123, fixes https://github.com/github/docs-content/issues/123
+            // Finds docs-content issues closed by the source PR body.
             const patterns = [
               /(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?):?\s+github\/docs-content#(\d+)/gi,
               /(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?):?\s+https:\/\/github\.com\/github\/docs-content\/issues\/(\d+)/gi,
@@ -168,7 +161,6 @@ jobs:
               return;
             }
 
-            // Query for parent issue via GraphQL
             const query = `
               query($nodeId: ID!) {
                 node(id: $nodeId) {
@@ -218,7 +210,6 @@ jobs:
             core.setOutput('parent_assignees', (parent.assignees?.nodes || []).map(a => a.login).join(','));
             core.setOutput('parent_repo', parent.repository.nameWithOwner);
 
-            // Also store the docs-content issue details
             core.setOutput('dc_issue_title', issue.title);
             core.setOutput('dc_issue_body', issue.body || '');
 
@@ -236,7 +227,6 @@ jobs:
             const prNumber = parseInt('${{ steps.resolve_pr.outputs.pr_number }}', 10);
             const prAuthor = '${{ steps.resolve_pr.outputs.pr_author }}';
 
-            // Get approved reviewers (exclude bots and PR author)
             const { data: reviews } = await github.rest.pulls.listReviews({
               owner: context.repo.owner,
               repo: context.repo.repo,
@@ -249,7 +239,6 @@ jobs:
                 .map(r => r.user.login)
             )];
 
-            // Get changed files (paths only, limit to 50)
             const { data: files } = await github.rest.pulls.listFiles({
               owner: context.repo.owner,
               repo: context.repo.repo,
@@ -297,15 +286,13 @@ jobs:
         with:
           github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
-            // Fetch changelog-internal.md from docs-content
             const { data } = await github.rest.repos.getContent({
               owner: 'github',
               repo: 'docs-content',
               path: 'docs-content-docs/docs-content-workflows/changelog-internal.md',
             });
             const changelog = Buffer.from(data.content, 'base64').toString('utf-8');
 
-            // Extract the first 3 entries (each starts with **date**)
             const lines = changelog.split('\n');
             let count = 0;
             let examples = [];
@@ -420,12 +407,8 @@ jobs:
         uses: actions/ai-inference@2c43c91ae16266ca159d311430343c67a5ffa222 # v3
         with:
           provider: copilot
-          # Must be an explicit empty string, not omitted. This action defaults
-          # `model` to "gpt-4.1" and always forwards it as --model, and that slug
-          # is retired, so omitting the input fails with:
-          #   Error: Model "gpt-4.1" from --model flag is not available.
-          # An empty string makes the action skip --model entirely and lets the
-          # Copilot CLI pick its own current default. See actions/ai-inference#271.
+          # Keep this empty string. Omitting it makes actions/ai-inference pass
+          # its retired gpt-4.1 default, which fails.
           model: ''
           prompt-file: prompt.txt
           system-prompt-file: system-prompt.txt
@@ -471,7 +454,6 @@ jobs:
             const branchName = `changelog-agent-${{ steps.resolve_pr.outputs.pr_number }}`;
             const filePath = 'docs-content-docs/docs-content-workflows/changelog-internal.md';
 
-            // Get the current changelog file from docs-content
             const { data: fileData } = await github.rest.repos.getContent({
               owner: 'github',
               repo: 'docs-content',
@@ -480,11 +462,9 @@ jobs:
 
             let changelog = Buffer.from(fileData.content, 'base64').toString('utf-8');
 
-            // Build the new entry
             const entry = `**${process.env.DATE_STR}**\n\n${process.env.DRAFT}\n\n<hr>`;
 
-            // Insert after the first H1 heading so leading frontmatter, comments,
-            // or blank lines do not affect placement.
+            // Insert after the first H1 heading so frontmatter, comments, or blank lines do not affect placement.
             const lines = changelog.split('\n');
             const headingIndex = lines.findIndex((line) => line.startsWith('# '));
 
@@ -498,14 +478,12 @@ jobs:
                 : `${beforeAndHeading}\n\n${entry}`;
             }
 
-            // Get the default branch SHA for creating a new branch
             const { data: ref } = await github.rest.git.getRef({
               owner: 'github',
               repo: 'docs-content',
               ref: 'heads/main',
             });
 
-            // Create the branch in docs-content
             try {
               await github.rest.git.createRef({
                 owner: 'github',
@@ -521,15 +499,13 @@ jobs:
               }
             }
 
-            // Fetch the file from the branch (handles both new and existing branches)
             const { data: branchFileData } = await github.rest.repos.getContent({
               owner: 'github',
               repo: 'docs-content',
               path: filePath,
               ref: branchName,
             });
 
-            // Update the changelog file on the new branch
             await github.rest.repos.createOrUpdateFileContents({
               owner: 'github',
               repo: 'docs-content',
@@ -544,7 +520,6 @@ jobs:
               },
             });
 
-            // Build credits for the PR body
             const reviewers = process.env.APPROVED_REVIEWERS
               ? process.env.APPROVED_REVIEWERS.split(',').map(r => `@${r}`).join(', ')
               : 'None';
@@ -586,7 +561,6 @@ jobs:
               draft: false,
             });
 
-            // Add labels
             try {
               await github.rest.issues.addLabels({
                 owner: 'github',
@@ -598,7 +572,6 @@ jobs:
               core.warning(`Failed to add labels: ${err.message}`);
             }
 
-            // Request review from PR author
             try {
               await github.rest.pulls.requestReviewers({
                 owner: 'github',
@@ -632,7 +605,6 @@ jobs:
             const author = process.env.PR_AUTHOR;
             const changelogPrUrl = process.env.CHANGELOG_PR_URL;
 
-            // Fetch GitHub-to-Slack mapping from docs-content
             let slackMapping = {};
             try {
               const { data } = await github.rest.repos.getContent({
@@ -648,7 +620,6 @@ jobs:
 
             const slackUserId = slackMapping[author];
 
-            // Build credits summary for the DM
             const reviewers = process.env.APPROVED_REVIEWERS
               ? process.env.APPROVED_REVIEWERS.split(',').join(', ')
               : 'none';
@@ -699,7 +670,6 @@ jobs:
               core.warning(`No Slack mapping found for GitHub user: ${author}`);
             }
 
-            // Fallback: post a GitHub comment on the source PR
             core.info('Falling back to GitHub comment notification.');
             await github.rest.issues.createComment({
               owner: context.repo.owner,
@@ -732,7 +702,7 @@ jobs:
               body: `<!-- changelog-agent-handled -->\n🤖 A changelog draft PR has been automatically created in docs-content: ${changelogPrUrl}`,
             });
 
-      # Local composite actions below require the repository to be checked out.
+      # Check out the repository before local composite actions run after a failure.
       - name: Check out repo
         if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

.github/workflows/check-for-spammy-issues.yml

@@ -1,8 +1,6 @@
 name: Check for Spammy Issues
 
-# **What it does**: This action closes low value issues in the open-source repository.
-# **Why we have it**: We get lots of spam in the open-source repository.
-# **Who does it impact**: Open-source contributors.
+# Closes low-value public issues so spam does not stay open in github/docs.
 
 on:
   issues:
@@ -39,24 +37,15 @@ jobs:
                 username: context.payload.sender.login,
               });
 
-              // Do not perform this workflow with GitHub employees. This return
-              // statement only gets hit if the user is a GitHub employee
+              // Skip GitHub employees so legitimate internal reports stay open.
               return
             } catch (err) {
-              // An error will be thrown if the user is not a GitHub employee
-              // If a user is not a GitHub employee, we should check to see if title has at least the minimum required number of words in it and if it does, we can exit the workflow
-
+              // The membership lookup throws for non-employees, so fall through to title checks.
               if (titleWordCount >= titleWordCountMin && !titleHasUrl && !titleHasDollarSign) {
                 return
               }
             }
 
-            //
-            // Assuming the user is not a GitHub employee and the issue title
-            // does not contain the minimum number of words required, proceed.
-            //
-
-            // Close the issue and add the invalid label
             await github.rest.issues.update({
               owner: owner,
               repo: repo,
@@ -65,15 +54,13 @@ jobs:
               state: 'closed'
             });
 
-            // Comment on the issue
             await github.rest.issues.createComment({
               owner: owner,
               repo: repo,
               issue_number: issue.number,
               body: `This issue may have been opened accidentally. I'm going to close it now, but feel free to open a new issue with a more descriptive title! Make sure not to include full URLs in your issue titles, and use paths instead.`
             });
 
-            // Add the issue to the Done column on the triage board
             try {
               await github.rest.projects.createCard({
                 column_id: 11167427,

.github/workflows/check-for-spammy-prs.yml

@@ -1,8 +1,6 @@
 name: Check for Spammy PRs
 
-# **What it does**: This action closes low value pull requests and PRs that do not target main.
-# **Why we have it**: We get lots of spam in the open-source repository.
-# **Who does it impact**: Open-source contributors.
+# Flags low-value public PRs and closes PRs that target branches other than main.
 
 on:
   pull_request_target: