Patch 4

.github/agents/readability-editor.md

@@ -12,60 +12,66 @@ You are an expert editor for the GitHub Docs content team. Your job is to maximi
 
 ## Agent Purpose
 
-- Enhance readability: Apply plain language, simplify sentences, and remove unnecessary jargon.
-- Use lists, logical headings, short paragraphs, and reorganize information if it helps readers quickly find key details.
+* Enhance readability: Apply plain language, simplify sentences, and remove unnecessary jargon.
+* Use lists, logical headings, short paragraphs, and reorganize information if it helps readers quickly find key details.
 
 ## Review Process
 
-- Read through the article once, noting barriers to readability.
-- Note barriers to scannability.
-- Note content with the weakest plain language usage.
-- Make changes according to the guidelines below.
-- Only analyze and edit the specific .md files provided.
-- Do not move or delete files, but you may suggest splitting or renaming if it improves the docs.
-- Make edits only when they provide meaningful improvements. Do not revise purely for minor aesthetics.
-- Do not remove sentences about defaults, feature scope, or access unless clearly repeated.
-- Retain essential usage details, admin options, and warnings unless obviously redundant.
-- Submit edits as a pull request.
+* Read through the article once, noting barriers to readability.
+* Note barriers to scannability.
+* Note content with the weakest plain language usage.
+* Make changes according to the guidelines below.
+* Only analyze and edit the specific .md files provided.
+* Do not move or delete files, but you may suggest splitting or renaming if it improves the docs.
+* Make edits only when they provide meaningful improvements. Do not revise purely for minor aesthetics.
+* After making edits, review each change to verify the original meaning is preserved. If a sentence's meaning would change, keep the original phrasing even if it is less concise.
+* Do not remove sentences about defaults, feature scope, or access unless clearly repeated.
+* Retain essential usage details, admin options, and warnings unless obviously redundant.
+* Submit edits as a pull request.
 
 ## Editing Guidelines and Plain Language Principles
 
 ### Writing Style
 
-- Use concise, everyday language. Explain or remove jargon when it doesn't explicitly support user understanding and the context of the article.
-- When two possible phrasings are equally clear, choose the one with fewer words. Brevity directly improves readability.
-- Use full terms and not their shortened versions.
-- Use active voice and personal pronouns ("you," "your"); favor present tense.
-- When “you can” introduces an instruction and does not convey optionality or permission, replace it with an active verb. For example, “You can enable” becomes “Enable”. Keep “you can” or add “optionally”/“if you want” when you need to express choice or permission.
-- Retain essential technical details, such as defaults, warnings, and admin options.
-- Do not alter the intent of verbs and actions (ex. "navigate" does not necessarily mean "select").
-- Start at least half of steps or instructions with a direct verb, unless another structure improves clarity.
-- Use sentence case for headings and list items (capitalize only the first word and proper nouns).
-- Match names of buttons, menus, and UI elements exactly as they appear in the original documentation. Do not paraphrase.
+* Use concise, everyday language. Explain or remove jargon when it doesn't explicitly support user understanding and the context of the article.
+* When two possible phrasings are equally clear, choose the one with fewer words. Brevity directly improves readability.
+* Use full terms and not their shortened versions.
+* Use active voice and personal pronouns ("you," "your"); favor present tense.
+* When "you can" introduces an instruction and does not convey optionality or permission, replace it with an active verb. For example, "You can enable" becomes "Enable". Keep "you can" or add "optionally"/"if you want" when you need to express choice or permission. When in doubt about whether "you can" conveys optionality, keep it.
+* Retain essential technical details, such as defaults, warnings, and admin options.
+* Do not alter the intent of verbs and actions (ex. "navigate" does not necessarily mean "select").
+* Never change the fundamental meaning of a sentence. Tightening prose is acceptable; altering what the sentence communicates is not. Specifically:
+  * Do not remove qualifiers like "we recommend," "we strongly recommend," or "it's best to" — these convey the strength of guidance.
+  * Do not remove connective phrases like "To do this," "The following," or "For more information" that orient the reader.
+  * Do not convert a description of capability ("Copilot can load tools when relevant") into a statement of fact ("Copilot loads tools when relevant").
+  * Do not change referential phrases like "the following" to "these" when "the following" points forward to a specific list or table.
+* Start at least half of steps or instructions with a direct verb, unless another structure improves clarity.
+* Use sentence case for headings and list items (capitalize only the first word and proper nouns).
+* Match names of buttons, menus, and UI elements exactly as they appear in the original documentation. Do not paraphrase.
 
 ### Structure
 
-- Don’t append new information or expository text to existing content.
-- Structure logically with clear, descriptive headings, short sections, and organized (bulleted or numbered) lists.
-- Do not create new headers if they would only have one sentence worth of content.
-- End every list item with a period if it is a complete sentence; omit periods for list fragments or single-word items.
+* Don't append new information or expository text to existing content. Do not invent examples, sample values, or illustrative bullet points that were not in the original article.
+* Structure logically with clear, descriptive headings, short sections, and organized (bulleted or numbered) lists.
+* Do not create new headers if they would only have one sentence worth of content.
+* End every list item with a period if it is a complete sentence; omit periods for list fragments or single-word items.
 
 ### Paragraphs
 
-- State the topic at the start of each paragraph; clarify connections between paragraphs.
-- Limit paragraphs to 150 words or fewer. 
-- Split a paragraph or list item when it includes two topics or steps.
+* State the topic at the start of each paragraph; clarify connections between paragraphs.
+* Limit paragraphs to 150 words or fewer. 
+* Split a paragraph or list item when it includes two topics or steps.
 
 ### Sentences
 
-- Write one idea per sentence; avoid redundancy, vague modifiers, and ambiguous phrasing.
-- Avoid consecutive sentences starting the same way.
-- Make sure no more than 25% of sentences contain more than 20 words.
-- Split sentences that contain multiple clauses into separate sentences.
+* Write one idea per sentence; avoid redundancy, vague modifiers, and ambiguous phrasing.
+* Avoid consecutive sentences starting the same way.
+* Make sure no more than 25% of sentences contain more than 20 words.
+* Split sentences that contain multiple clauses into separate sentences.
 
 ## References
 
 These PRs demonstrate successful improvement in readability:
-- https://github.com/github/docs-internal/pull/59219
-- https://github.com/github/docs-internal/pull/59300
-- https://github.com/github/docs-internal/pull/57154
+* https://github.com/github/docs-internal/pull/59219
+* https://github.com/github/docs-internal/pull/59300
+* https://github.com/github/docs-internal/pull/57154

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

@@ -29,7 +29,7 @@ jobs:
 
       - name: Check team membership
         id: membership_check
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |

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

@@ -50,7 +50,7 @@ jobs:
 
       # Because we get far too much spam ;_;
       - name: Lock conversations
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
         env:
           PR_NUMBER: ${{ github.event.pull_request.number }}
         with:

.github/workflows/benchmark-pages.yml

@@ -44,7 +44,7 @@ jobs:
           npx tsx src/workflows/benchmark-pages.ts \
             --versions "free-pro-team@latest,enterprise-cloud@latest,enterprise-server@latest" \
             --modes article-body \
-            --slow 500 \
+            --slow 1000 \
             --json /tmp/benchmark-results.json | tee /tmp/benchmark-output.txt
 
       - name: Check results and create issue if needed
@@ -108,7 +108,7 @@ jobs:
             echo "**Total pages:** $TOTAL"
             echo "**Stats:** p50=${P50}ms · p99=${P99}ms · max=${MAX}ms"
             echo "**Errors:** $ERRORS"
-            echo "**Slow (≥500ms):** $SLOW"
+            echo "**Slow (≥1000ms):** $SLOW"
           } > "$BODY_FILE"
 
           if [ "$ERRORS" -gt 0 ]; then

.github/workflows/changelog-prompt.yml

@@ -20,7 +20,7 @@ jobs:
     steps:
       - name: Check if PR author is in docs-content team
         id: check_team
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
@@ -41,7 +41,7 @@ jobs:
 
         if: env.CONTINUE_WORKFLOW == 'true'
 
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |

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

@@ -17,7 +17,7 @@ jobs:
     if: github.repository == 'github/docs'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
         with:
           github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |

.github/workflows/close-bad-repo-sync-prs.yml

@@ -22,7 +22,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Close pull request if unwanted
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
         with:
           github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |

.github/workflows/confirm-internal-staff-work-in-docs.yml

@@ -24,7 +24,7 @@ jobs:
     if: github.repository == 'github/docs' && github.actor != 'docs-bot'
     steps:
       - id: membership_check
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
         env:
           TEAM_CONTENT_REPO: ${{ secrets.TEAM_CONTENT_REPO }}
         with:

.github/workflows/copy-api-issue-to-internal.yml

@@ -19,7 +19,7 @@ jobs:
     if: github.event.label.name == 'fix-internally' && github.repository == 'github/docs'
     steps:
       - name: Check if this run was triggered by a member of the docs team
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
         id: triggered-by-member
         with:
           github-token: ${{secrets.DOCS_BOT_PAT_BASE}}

.github/workflows/create-changelog-pr.yml

@@ -34,7 +34,7 @@ jobs:
 
       - name: Check that the user belongs to the github org
         id: hubber_check
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
         with:
           github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
@@ -105,7 +105,7 @@ jobs:
 
       - name: Create a pull request
         if: env.CONTINUE_WORKFLOW == 'true'
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
         id: create_pull_request
         with:
           github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
@@ -124,7 +124,7 @@ jobs:
 
       - name: Add 'ready-for-doc-review' and 'skip FR board' labels to PR
         if: env.CONTINUE_WORKFLOW == 'true'
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
         env:
           # Get the number of the PR that was just created:
           PULL_REQUEST_NUMBER: ${{ steps.create_pull_request.outputs.pull-request-number }}
@@ -140,7 +140,7 @@ jobs:
 
       - name: Assign PR to commenter
         if: env.CONTINUE_WORKFLOW == 'true'
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
         env:
           # Reuse the PR number captured earlier
           PULL_REQUEST_NUMBER: ${{ steps.create_pull_request.outputs.pull-request-number }}

.github/workflows/delete-orphan-translation-files.yml

@@ -133,7 +133,28 @@ jobs:
             --label "workflow-generated" \
             --head=$branch_name
           echo "Merge created PR..."
-          retry_command gh pr merge --merge --auto --delete-branch "$branch_name"
+          # Prefer enabling auto-merge so the PR waits for any required
+          # checks before merging. If auto-merge can't be enabled — usually
+          # because all required checks completed before this step ran and
+          # the PR is already immediately mergeable — fall back to a direct
+          # merge. GitHub returns one of these misleading errors in that
+          # case: "Branch does not have required protected branch rules",
+          # "Pull request is in unstable status", or "Pull request is not
+          # in a mergeable state".
+          auto_merge_err=$(mktemp)
+          trap 'rm -f "$auto_merge_err"' EXIT
+          if retry_command gh pr merge --merge --auto --delete-branch "$branch_name" 2>"$auto_merge_err"; then
+            :
+          else
+            cat "$auto_merge_err"
+            if grep -qE "does not have required protected branch rules|unstable status|Pull request is not in a mergeable state" "$auto_merge_err"; then
+              echo "Auto-merge unavailable; PR appears immediately mergeable. Falling back to direct merge."
+              retry_command gh pr merge --merge --delete-branch "$branch_name"
+            else
+              echo "Auto-merge failed with an unexpected error."
+              exit 1
+            fi
+          fi
 
       - uses: ./.github/actions/slack-alert
         if: ${{ failure() && github.event_name != 'workflow_dispatch' }}

.github/workflows/feedback-prompt.yml

@@ -20,7 +20,7 @@ jobs:
     steps:
       - name: Check if PR author is in docs-content team
         id: check_team
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |
@@ -41,7 +41,7 @@ jobs:
 
         if: env.NON_DOCS_HUBBER == 'true'
 
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |

.github/workflows/hubber-contribution-help.yml

@@ -26,7 +26,7 @@ jobs:
         uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
       - id: membership_check
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
         with:
           github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           script: |

.github/workflows/index-general-search-pr.yml

@@ -64,7 +64,7 @@ jobs:
 
           # first sleep to give it a chance to start
           sleep 6
-          curl --retry-connrefused --retry 4 -I http://localhost:4002/
+          curl --retry-connrefused --retry 6 -I http://localhost:4002/
 
       - if: ${{ failure() }}
         name: Debug server outputs on errors

.github/workflows/index-general-search.yml

@@ -49,7 +49,7 @@ jobs:
     outputs:
       matrix: ${{ steps.set-matrix.outputs.result }}
     steps:
-      - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         id: set-matrix
         with:
           script: |

.github/workflows/merged-notification.yml

@@ -20,7 +20,7 @@ jobs:
     if: github.repository == 'github/docs' && github.event.pull_request.merged && github.event.pull_request.base.ref == github.event.repository.default_branch && github.event.pull_request.user.login != 'docs-bot'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
         with:
           script: |
             github.rest.issues.createComment({

.github/workflows/move-existing-issues-to-the-correct-repo.yml

@@ -16,7 +16,7 @@ jobs:
     if: github.repository == 'github/docs-internal'
     steps:
       - id: move_to_correct_repo
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
         env:
           TEAM_ENGINEERING_REPO: ${{ secrets.TEAM_ENGINEERING_REPO }}
           TEAM_CONTENT_REPO: ${{ secrets.TEAM_CONTENT_REPO }}

.github/workflows/move-reopened-issues-to-triage.yaml

@@ -18,7 +18,7 @@ jobs:
     if: github.repository == 'github/docs'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
         with:
           script: |
             const issueNumber = context.issue.number;

.github/workflows/needs-sme-stale-check.yaml

@@ -41,3 +41,8 @@ jobs:
         with:
           slack_channel_id: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }}
           slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
+
+      - uses: ./.github/actions/create-workflow-failure-issue
+        if: ${{ failure() }}
+        with:
+          token: ${{ secrets.DOCS_BOT_PAT_BASE }}

.github/workflows/no-response.yaml

@@ -63,3 +63,8 @@ jobs:
         with:
           slack_channel_id: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }}
           slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
+
+      - uses: ./.github/actions/create-workflow-failure-issue
+        if: ${{ failure() }}
+        with:
+          token: ${{ secrets.DOCS_BOT_PAT_BASE }}

.github/workflows/notify-about-deployment.yml

@@ -75,3 +75,8 @@ jobs:
         with:
           slack_channel_id: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }}
           slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
+
+      - uses: ./.github/actions/create-workflow-failure-issue
+        if: ${{ failure() }}
+        with:
+          token: ${{ secrets.DOCS_BOT_PAT_BASE }}