Merge branch 'main' into claude/stacked-prs-auto-merge-docs-rm35z8

Author: mchammer01

.devcontainer/Dockerfile

@@ -1,4 +1,4 @@
 # Update ARG and FROM together from the Node devcontainer image tags:
 # https://mcr.microsoft.com/en-us/product/devcontainers/javascript-node/tags
 ARG VARIANT=dev-24-bookworm
-FROM mcr.microsoft.com/devcontainers/javascript-node:dev-24-bookworm@sha256:d0445b9546f96869b509aa70b8593bdc0054aca6689bc1dd0324083d0fd2bcc3
+FROM mcr.microsoft.com/devcontainers/javascript-node:dev-24-bookworm@sha256:42a1a7629b5a2c22c759a1de4fbb277c9e600b6fecd66b89583fc36e9453e698

.github/CONTRIBUTING.md

@@ -76,7 +76,7 @@ For complete style guidance, see our [style guide](https://docs.github.com/en/co
 
 #### Repository-specific options:
 
-**Make changes in the UI:** Click **Make a contribution** at the bottom of any docs page for small changes like typos or broken links.
+**Make changes in the UI:** For small changes like typos or broken links, click **Make a contribution** at the bottom of any docs page. The button opens the article's source file in this repository. Click the pencil icon to edit the file. GitHub asks you to fork the repository, then lets you propose your change as a pull request. See "[Editing files in another user's repository](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files#editing-files-in-another-users-repository)."
 
 <img src="/contributing/images/contribution_cta.png" />
 

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

@@ -1,10 +1,12 @@
 name: Check for Spammy Issues
 
-# Closes low-value public issues so spam does not stay open in github/docs.
+# Closes low-value public issues and issues with emoji titles in github/docs.
+# GitHub employees, docs-bot, and the skip-spammy-check label are exempt.
+# Add skip-spammy-check before reopening an issue whose title still contains emoji.
 
 on:
   issues:
-    types: [opened]
+    types: [opened, edited, reopened]
 
 permissions:
   contents: read
@@ -13,58 +15,78 @@ jobs:
   spammy-title-check:
     name: Remove issues with spammy titles
     if: github.repository == 'github/docs'
+    concurrency:
+      group: ${{ github.workflow }}-spammy-title-${{ github.event.issue.number }}
+      cancel-in-progress: false
     runs-on: ubuntu-latest
     steps:
       - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
         with:
           github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
+            const params = { ...context.repo, issue_number: context.payload.issue.number }
 
-            const issue = context.payload.issue
-            const owner = 'github'
-            const repo = 'docs'
+            // Events can predate title edits or an exemption label, so read the current issue.
+            const { data: issue } = await github.rest.issues.get(params)
+            if (issue.state !== 'open' || issue.user.login === 'docs-bot') {
+              return
+            }
+            if (issue.labels.some(label => label.name.toLowerCase() === 'skip-spammy-check')) {
+              core.info('Skipping because the issue has the skip-spammy-check label.')
+              return
+            }
 
             const titleWordCount = issue.title.trim().split(' ').length
             const titleWordCountMin = 3
             const urlRegex = /https?:\/\/\S+/i
             const titleHasUrl = urlRegex.test(issue.title)
             const titleHasDollarSign = issue.title.includes('$')
+            // Text-default symbols need an emoji selector; plain digits, #, and * need a keycap.
+            const titleHasEmoji = /\p{Emoji_Presentation}(?!\uFE0E)|\p{Extended_Pictographic}\uFE0F|[#*0-9]\uFE0F?\u20E3/u.test(issue.title)
+            // Keep the existing non-emoji heuristics limited to newly opened issues.
+            const hasOtherSpam = context.payload.action === 'opened' &&
+              (titleWordCount < titleWordCountMin || titleHasUrl || titleHasDollarSign)
+            if (!titleHasEmoji && !hasOtherSpam) {
+              return
+            }
 
             try {
               await github.rest.teams.getMembershipForUserInOrg({
                 org: 'github',
                 team_slug: 'employees',
-                username: context.payload.sender.login,
-              });
+                username: issue.user.login,
+              })
 
               // Skip GitHub employees so legitimate internal reports stay open.
               return
             } catch (err) {
-              // The membership lookup throws for non-employees, so fall through to title checks.
-              if (titleWordCount >= titleWordCountMin && !titleHasUrl && !titleHasDollarSign) {
-                return
+              // Only a missing membership means non-employee; other failures must stop moderation.
+              if (err.status !== 404) {
+                throw err
               }
             }
 
-            await github.rest.issues.update({
-              owner: owner,
-              repo: repo,
-              issue_number: issue.number,
+            await github.rest.issues.addLabels({
+              ...params,
               labels: ['invalid'],
-              state: 'closed'
-            });
+            })
+
+            await github.rest.issues.update({
+              ...params,
+              state: 'closed',
+            })
 
             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.`
-            });
+              ...params,
+              body: titleHasEmoji
+                ? 'Closing because the title contains emoji. Please remove the emoji and open a new issue.'
+                : `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.`,
+            })
 
             try {
               await github.rest.projects.createCard({
                 column_id: 11167427,
-                content_id: context.payload.issue.id,
+                content_id: issue.id,
                 content_type: "Issue"
               });
             } catch (error) {

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

@@ -1,6 +1,7 @@
 name: Check for Spammy PRs
 
-# Flags low-value public PRs and closes PRs that target branches other than main.
+# Flags low-value public PRs and closes PRs with non-main targets or emoji titles.
+# Maintainers add the skip-spammy-check label to exempt a PR.
 
 on:
   pull_request_target:
@@ -9,14 +10,63 @@ on:
 permissions:
   contents: read
   issues: read
-  pull-requests: write
 
 jobs:
+  emoji-title-check:
+    name: Close PRs with emoji titles
+    if: github.repository == 'github/docs'
+    concurrency:
+      group: ${{ github.workflow }}-emoji-title-${{ github.event.pull_request.number }}
+      cancel-in-progress: false
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
+        with:
+          github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
+          script: |
+            const item = context.payload.pull_request
+            const params = { ...context.repo, issue_number: item.number }
+
+            // Events can predate title edits or an exemption label, so read the current PR.
+            const { data: current } = await github.rest.issues.get(params)
+            if (current.state !== 'open' || current.user.login === 'docs-bot') {
+              return
+            }
+
+            // Text-default symbols need an emoji selector; plain digits, #, and * need a keycap.
+            const hasEmoji = /\p{Emoji_Presentation}(?!\uFE0E)|\p{Extended_Pictographic}\uFE0F|[#*0-9]\uFE0F?\u20E3/u.test(current.title)
+            if (!hasEmoji) {
+              return
+            }
+
+            if (current.labels.some(label => label.name.toLowerCase() === 'skip-spammy-check')) {
+              core.info('Skipping because the pull request has the skip-spammy-check label.')
+              return
+            }
+
+            // Mark automated closures so the skip label can trigger the existing recovery workflow.
+            await github.rest.issues.addLabels({
+              ...params,
+              labels: ['invalid'],
+            })
+
+            await github.rest.pulls.update({
+              ...context.repo,
+              pull_number: item.number,
+              state: 'closed',
+            })
+
+            await github.rest.issues.createComment({
+              ...params,
+              body: 'Closing because the title contains emoji. Please remove the emoji and open a new PR.',
+            })
+
   spammy-pr-check:
     name: Label spammy PRs and reject non-main targets
     if: >
       github.repository == 'github/docs' && github.event_name == 'pull_request_target' &&
-      github.event.pull_request.user.login != 'docs-bot'
+      github.event.pull_request.user.login != 'docs-bot' &&
+      !contains(github.event.pull_request.labels.*.name, 'skip-spammy-check')
     runs-on: ubuntu-latest
     steps:
       - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
@@ -48,6 +98,21 @@ jobs:
               return changedLines.length > 0 &&
                 changedLines.every(line => line.slice(1).trim() === '')
             })
+            const onlyBreaksOpeningFrontmatter = files.length > 0 && files.every(file => {
+              if (
+                file.status !== 'modified' ||
+                !file.filename.startsWith('content/') ||
+                !file.filename.endsWith('.md') ||
+                file.additions !== 1 ||
+                file.deletions !== 1
+              ) return false
+
+              const lines = (file.patch || '').split('\n')
+              return /^@@ -1(?:,\d+)? \+1(?:,\d+)? @@/.test(lines[0]) &&
+                lines[1] === '----' && // Diff prefix "-" followed by the original "---".
+                lines[2]?.startsWith('+') &&
+                !/^---(?:\s*yaml)?\s*$/i.test(lines[2].slice(1))
+            })
             const onlyRenames = files.length > 0 && files.every(
               f => f.status === 'renamed' && f.additions === 0 && f.deletions === 0
             )
@@ -99,9 +164,22 @@ jobs:
               isEmptyCommit ||
               touchesTooMany ||
               isBlankLineEdit ||
+              onlyBreaksOpeningFrontmatter ||
               onlyRenames ||
               onlyIndexMd
             ) {
+              // The payload can predate a label added right after the PR opened, so read the labels again.
+              const { data: currentLabels } = await github.rest.issues.listLabelsOnIssue({
+                owner,
+                repo,
+                issue_number: pull_number,
+                per_page: 100,
+              })
+              if (currentLabels.some(label => label.name.toLowerCase() === 'skip-spammy-check')) {
+                core.info('Skipping because the pull request has the skip-spammy-check label.')
+                return
+              }
+
               await github.rest.issues.addLabels({
                 owner,
                 repo,

.github/workflows/close-on-invalid-label.yaml

@@ -1,23 +1,27 @@
 name: Close issue/PR on adding invalid label
 
 # Closes public issues and PRs when the invalid label is added.
+# Re-closes invalid PRs that someone without write access reopens.
+# Reopens PRs closed as invalid when maintainers add the skip-spammy-check label.
 
 on:
   issues:
     types: [labeled]
-  # pull_request_target lets the workflow close forked PRs after the invalid label is added.
+  # pull_request_target lets the workflow close or reopen forked PRs when they're labeled or reopened.
   pull_request_target:
-    types: [labeled]
+    types: [labeled, reopened]
 
 permissions:
   contents: read
-  issues: write
-  pull-requests: write
 
 jobs:
   close-on-adding-invalid-label:
     if: github.repository == 'github/docs' && github.event.label.name == 'invalid'
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
 
     steps:
       - name: Close issue
@@ -42,3 +46,99 @@ jobs:
         if: ${{ failure() && github.event_name != 'pull_request_target' }}
         with:
           slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
+
+  # Authors can reopen PRs they closed themselves, even after the invalid label is added.
+  reclose-reopened-invalid-pr:
+    if: >
+      github.repository == 'github/docs' && github.event_name == 'pull_request_target' &&
+      github.event.action == 'reopened' &&
+      contains(github.event.pull_request.labels.*.name, 'invalid')
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Re-close PR unless reopened by someone with write access
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          SENDER: ${{ github.event.sender.login }}
+        run: |
+          if ! permission=$(gh api "repos/$GITHUB_REPOSITORY/collaborators/$SENDER/permission" --jq '.permission'); then
+            echo "::warning::Couldn't look up permission for $SENDER, so treating them as read-only."
+            permission=none
+          fi
+          if [[ "$permission" == "admin" || "$permission" == "write" ]]; then
+            echo "$SENDER has $permission access, so leaving the PR open."
+            exit 0
+          fi
+          gh pr close "$PR_URL" --comment 'This pull request is labeled `invalid`, so only maintainers can reopen it. If you think this is incorrect, please mention this in a corresponding issue.'
+
+  # Maintainers add skip-spammy-check to recover a PR that automated checks closed as invalid.
+  reopen-on-adding-skip-label:
+    if: github.repository == 'github/docs' && github.event_name == 'pull_request_target' && github.event.label.name == 'skip-spammy-check'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          # A PAT makes the reopen trigger other workflows, such as triage, like a manual reopen.
+          github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
+          script: |
+            const { owner, repo } = context.repo
+            const pull_number = context.payload.pull_request.number
+
+            // The event payload can be stale by the time this job runs, so read the current state.
+            const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number })
+            const labels = pr.labels.map(label => label.name.toLowerCase())
+
+            if (pr.merged || pr.state !== 'closed') {
+              core.info('The pull request is not closed, so there is nothing to reopen.')
+              return
+            }
+
+            if (!labels.includes('skip-spammy-check')) {
+              core.info('The pull request no longer has the skip-spammy-check label.')
+              return
+            }
+
+            // Automated checks add the invalid label before closing, so PRs without it were closed for another reason.
+            if (!labels.includes('invalid')) {
+              core.info('The pull request was not closed as invalid, so it stays closed.')
+              return
+            }
+
+            try {
+              await github.rest.pulls.update({ owner, repo, pull_number, state: 'open' })
+            } catch (error) {
+              if (error.status !== 422) throw error
+
+              // GitHub refuses to reopen a PR after its head or base branch was deleted or force-pushed.
+              core.warning(`Could not reopen the pull request: ${error.message}`)
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number: pull_number,
+                body: 'I could not reopen this pull request automatically, most likely because its head or base branch was deleted or force-pushed after it was closed. Restore the branch, then remove and re-add the `skip-spammy-check` label to retry automatic reopening and removal of the `invalid` label.',
+              })
+              return
+            }
+
+            try {
+              await github.rest.issues.removeLabel({
+                owner,
+                repo,
+                issue_number: pull_number,
+                name: 'invalid',
+              })
+            } catch (error) {
+              // A maintainer or an earlier run may have removed the label already.
+              if (error.status !== 404) throw error
+            }
+
+            await github.rest.issues.createComment({
+              owner,
+              repo,
+              issue_number: pull_number,
+              body: 'The `skip-spammy-check` label was added, so I removed the `invalid` label and reopened this pull request. The spammy pull request check skips it while the label is applied.',
+            })

.github/workflows/close-prs-not-targeting-main.yml

@@ -1,6 +1,6 @@
 name: Reject PRs targeting non-default branch (scheduled)
 
-# Backup check for check-for-spammy-prs.yml: closes PRs that don't target main
+# Backup check for check-for-spammy-prs.yml: closes PRs that don't target main, unless they have the skip-spammy-check label
 
 on:
   schedule:
@@ -39,6 +39,9 @@ jobs:
               if (pr.user.login === 'docs-bot') continue
 
               const labels = pr.labels.map(l => l.name)
+              // Maintainers add this label to allow a PR that targets another branch.
+              if (labels.some(label => label.toLowerCase() === 'skip-spammy-check')) continue
+
               if (!labels.includes('invalid')) {
                 await github.rest.issues.addLabels({
                   owner,