Merge branch 'main' into gem-clarification-reusable

Author: Sharra-writes

.github/actions/retry-command/action.yml

@@ -7,11 +7,11 @@ inputs:
   max_attempts:
     description: 'Maximum number of retry attempts'
     required: false
-    default: '8'
+    default: '12'
   delay:
     description: 'Delay between attempts in seconds'
     required: false
-    default: '15'
+    default: '30'
 
 runs:
   using: 'composite'

.github/copilot-instructions.md

@@ -1,4 +1,44 @@
-This documentation repository consists mainly of content written in Markdown format. These files are converted into HTML for displaying on a website. Most Markdown files become a single article on the documentation site. Other files contain reusable content which is inserted into multiple articles. The repository also contains YAML files (e.g. for variable text), image files, JavaScript/TypeScript files, etc.
+This repository contains code to run the GitHub Docs site on docs.github.com, as well as the content that is displayed on the site. The code is written in JavaScript and TypeScript, and the content is primarily written in Markdown.
+
+Changes to files in `src/*` or files with `.ts` or `.js` extensions are likely code-related changes. Please follow the engineering guidelines below when making changes to these files.
+
+Changes to files in `content/*` and `data/*` are likely content-related changes. Content changes include updates to articles, reusable content, and data files that define variables used in articles. Please follow the content guidelines below when making changes to these files.
+
+## Engineering guidelines
+
+### Scripts
+
+All scripts can be found in `package.json`.
+
+To validate any code changes:
+   - `npm run tsc`
+   - `npm run build`
+   - `npm run prettier`
+   - `npm run lint`: you can include `-- --fix`
+
+To validate specific changes,
+  - `npm run test`: For all unit tests
+    - You can pass specific paths, e.g. `npm run test -- src/search/tests/ai-search-proxy`
+    - You can add `--silent=false` to include `console.log` debugging.
+  - `npm run build && npm run playwright-test -- playwright-rendering`: You need to build for changes outside of the test to be picked up. We use playwright for all rendering and end-to-end tests
+    - You can add `--ui` to keep open `localhost:4000` which can be viewed in a simple browser for debugging UI state.
+  - `npm run dev` to start the development server on `localhost:4000`.
+
+### Imports
+
+We use absolute imports, relative to the `src` directory, using the `@` symbol.
+
+For example, `getRedirect` which lives inn `src/redirects/lib/get-redirect.js` can be imported with `import getRedirect from '@/redirects/lib/get-redirect'`.
+
+The same rule applies for TypeScript (`.ts`) imports, e.g. `import type { GeneralSearchHit } from '@/search/types'`
+
+### Testing changes
+
+We use `vitest` to write unit tests. Tests live in their own files in the `tests` subdirectory of a source (src) directory, e.g. `src/search/tests/api-ai-search.ts`. 
+
+For integration tests, we can use the mock server in `src/tests/mocks/start-mock-server.ts` to mock exteneral requests. 
+
+For UI rendering tests, we use `playwright` and write tests in `src/fixtures/tests/playwright-rendering.spec.ts`
 
 ## Content guidelines
 
@@ -90,31 +130,11 @@ Then, within a collapsed section, quote the original prompt from Copilot Chat:
 
 This helps reviewers understand the context and intent behind the automated changes.
 
-## Development and testing guidelines
-
-### Content changes
+### Testing Content changes
 
 Before committing content changes, always:
 
 1. **Use the content linter** to validate content: `npm run lint-content -- --paths <file-paths>`
 2. **Check for proper variable usage** in your content
 3. **Verify [AUTOTITLE] links** point to existing articles
 4. **Run tests** on changed content: `npm run test -- src/content-render/tests/render-changed-and-deleted-files.js`
-
-### Script and code changes
-
-For TypeScript, JavaScript, and SCSS files:
-
-1. **Run Prettier** to check formatting: `npm run prettier-check`
-2. **Run the linter**: `npm run lint`
-3. **Run TypeScript checks**: `npm run tsc`
-4. **Run relevant tests**: `npm test`
-
-### Environment setup
-
-When testing changes in your development environment:
-
-1. Install dependencies: `npm ci`
-2. For content changes, ensure the content linter runs successfully
-3. For script changes, ensure all formatting and linting checks pass
-4. Always verify your changes don't break existing functionality

.github/dependabot.yml

@@ -5,7 +5,7 @@ registries:
     type: docker-registry
     url: ghcr.io
     username: PAT
-    password: ${{secrets.CONTAINER_BUILDER_TOKEN}}
+    password: ${{secrets.BASE_CONTAINER_IMAGE_READER_DEPENDABOT}}
 
 updates:
   - package-ecosystem: npm

.github/workflows/lint-entire-content-data-markdown.yml

@@ -41,7 +41,7 @@ jobs:
           REPORT_AUTHOR: docs-bot
           REPORT_LABEL: broken content markdown report
           REPORT_REPOSITORY: github/docs-content
-        run: npm run post-lints -- --path /tmp/lint-results.json
+        run: npm run lint-report -- --path /tmp/lint-results.json
 
       - uses: ./.github/actions/slack-alert
         if: ${{ failure() && github.event_name != 'workflow_dispatch' }}

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

@@ -1,12 +1,12 @@
 name: Stale check for issues or PRs with "needs SME" label
 
-# **What it does**: Provides stale checks on issues/PRs that need SME(subject matter expert) review on open source docs repo.
-# **Why we have it**: In the open repo, we want we want frequent checks on issues/PRs that are waiting on SME review.
+# **What it does**: Runs only in the OS repository to provide stale checks on issues/PRs that need SME(subject matter expert) review.
+# **Why we have it**: In the open repo, we want we want to check on issues/PRs that are waiting on SME review.
 # **Who does it impact**: Anyone working in the open repo.
 
 on:
   schedule:
-    - cron: '20 16 * * *' # Run each day at 16:20 UTC / 8:20 PST
+    - cron: '20 16 * * 3' # Run each Wedneday at 16:20 UTC / 8:20 PST
 
 permissions:
   contents: read
@@ -22,15 +22,17 @@ jobs:
       - uses: actions/stale@28ca1036281a5e5922ead5184a1bbf96e5fc984e # v9.0.0
         with:
           only-labels: needs SME
-          remove-stale-when-updated: true
           days-before-stale: 28 # adds stale label if no activity for 7 days - temporarily changed to 28 days as we work through the backlog
-          stale-issue-message: 'This is a gentle bump for the docs team that this issue is waiting for technical review.'
-          stale-issue-label: SME stale
+          stale-issue-message: 'This is a gentle reminder for the docs team that this issue is waiting for technical review by a subject matter expert (SME).'
+          stale-issue-label: 'Waiting on SME review'
           days-before-issue-close: -1 # never close
-          stale-pr-message: 'This is a gentle bump for the docs team that this PR is waiting for technical review.'
-          stale-pr-label: SME stale
+          stale-pr-message: 'This is a gentle reminder for the docs team that this PR is waiting for technical review by a subject matter expert.'
+          stale-pr-label: 'Waiting on SME review'
           days-before-pr-close: -1 # never close
 
+      - name: Print outputs
+        run: echo "Staled issues/PRs:${{ steps.stale.outputs.staled-issues-prs || '0' }}, Closed issues/PRs:${{ steps.stale.outputs.closed-issues-prs || '0' }}"
+
       - name: Check out repo
         if: ${{ failure() }}
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

.github/workflows/no-response.yaml

@@ -1,18 +1,18 @@
-name: No Response
+name: Stale check for no response from author
 
-# **What it does**: Closes issues that don't have enough information to be
+# **What it does**: Runs only in the OS repository to close issues that don't have enough information to be
 #                   actionable.
 # **Why we have it**: To remove the need for maintainers to remember to check
 #                     back on issues periodically to see if contributors have
 #                     responded.
-# **Who does it impact**: Everyone that works on docs or docs-internal.
+# **Who does it impact**: Everyone that works in the docs repository.
 
 on:
   issue_comment:
     types: [created]
 
   schedule:
-    - cron: '20 * * * *' # Run each hour at 20 minutes past
+    - cron: '20 16 * * 1' # Run each Monday at 16:20 UTC / 8:20 PST
 
 permissions:
   contents: read
@@ -28,10 +28,11 @@ jobs:
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           only-labels: 'more-information-needed'
-          days-before-stale: -1
-          days-before-issue-stale: 14
-          days-before-close: -1
-          days-before-issue-close: 0
+
+          # Define behavior for issues
+          days-before-issue-stale: 21
+          days-before-issue-close: 1 # close after 1 day if the issue is not updated
+          stale-issue-label: 'Waiting on contributor'
           close-issue-message: >
             This issue has been automatically closed because there has been no response
             to our request for more information from the original author. With only the
@@ -40,13 +41,19 @@ jobs:
             that we can investigate further. See [this blog post on bug reports and the
             importance of repro steps](https://www.lee-dohm.com/2015/01/04/writing-good-bug-reports/)
             for more information about the kind of information that may be helpful.
-          days-before-pr-stale: 7
-          days-before-pr-close: 0
+
+          # Define behavior for pull requests
+          days-before-pr-stale: 21
+          days-before-pr-close: 1 # close after a day if no activity is detected
+          stale-pr-label: 'Waiting on contributor'
           close-pr-message: >
             This PR has been automatically closed because there has been no response to
             to our request for more information from the original author. Please reach out
-            if you have the information we requested, or open a [new issue](https://github.com/github/docs/issues/new/choose)
-            to describe your changes. Then we can begin the review process.
+            if you have the information we requested, or open an [issue](https://github.com/github/docs/issues/new/choose)
+            to describe your changes. Then we can reopen this PR and begin the review process.
+
+      - name: Print outputs
+        run: echo "Staled issues/PRs:${{ steps.stale.outputs.staled-issues-prs || '0' }}, Closed issues/PRs:${{ steps.stale.outputs.closed-issues-prs || '0' }}"
 
       - name: Check out repo
         if: ${{ failure() }}

.github/workflows/stale.yml

@@ -1,36 +1,40 @@
-name: Stale
+name: Stale check for stalled pull requests in the docs-internal repository
 
-# **What it does**: Close issues and pull requests after no updates for 365 days.
-# **Why we have it**: We want to manage our queue of issues and pull requests.
-# **Who does it impact**: Everyone that works on docs or docs-internal.
+# **What it does**: Identifies pull requests that have been inactive for 30 days.
+# **Why we have it**: We want to avoid pull requests that are stalled and not being reviewed.
+# **Who does it impact**: Everyone that works in the internal repository.
 
 on:
   schedule:
-    - cron: '20 16 * * *' # Run every day at 16:20 UTC / 8:20 PST
+    - cron: '20 16 * * 1' # Run each Monday at 16:20 UTC / 8:20 PST
+  push:
+    paths:
+      - .github/workflows/stale.yml
 
 permissions:
   contents: read
-  issues: write
   pull-requests: write
+  issues: write
 
 jobs:
   stale:
-    if: github.repository == 'github/docs-internal' || github.repository == 'github/docs'
+    if: github.repository == 'github/docs-internal'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/stale@28ca1036281a5e5922ead5184a1bbf96e5fc984e # v9.0.0
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
-          stale-issue-message: 'This issue is stale because there have been no updates in 365 days.'
-          stale-pr-message: 'This PR is stale because there have been no updates in 365 days.'
-          days-before-stale: 365
-          days-before-close: 0
-          stale-issue-label: 'stale'
+          stale-pr-message: "It looks as if this pull request has been inactive for 30 days. We want to check in with you to see if you plan to continue working on it. If you do, please add a comment to let us know. If we don't hear from you, we will close this pull request after 14 days."
+          days-before-stale: 30
+          days-before-close: 14
           stale-pr-label: 'stale'
-          exempt-pr-labels: 'never-stale,waiting for review'
-          exempt-issue-labels: 'never-stale,help wanted,waiting for review'
-          operations-per-run: 1000
-          close-issue-reason: not_planned
+          exempt-pr-labels: 'never-stale'
+          close-pr-label: 'Closed as inactive'
+
+          operations-per-run: 150
+
+      - name: Print outputs
+        run: echo "Staled PRs:${{ steps.stale.outputs.staled-issues-prs || '0' }}, Closed PRs:${{ steps.stale.outputs.closed-issues-prs || '0' }}"
 
       - name: Check out repo
         if: ${{ failure() }}

.github/workflows/sync-graphql.yml

@@ -17,11 +17,16 @@ jobs:
   update_graphql_files:
     if: github.repository == 'github/docs-internal'
     runs-on: ubuntu-latest
+    outputs:
+      ignored-changes: ${{ steps.sync.outputs.ignored-changes }}
+      ignored-count: ${{ steps.sync.outputs.ignored-count }}
+      ignored-types: ${{ steps.sync.outputs.ignored-types }}
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       - uses: ./.github/actions/node-npm-setup
       - name: Run updater scripts
+        id: sync
         env:
           # need to use a token from a user with access to github/github for this step
           GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
@@ -70,3 +75,22 @@ jobs:
         with:
           slack_channel_id: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }}
           slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
+
+  notify_ignored_changes:
+    if: github.repository == 'github/docs-internal' && needs.update_graphql_files.outputs.ignored-count > 0 && github.event_name != 'workflow_dispatch'
+    needs: update_graphql_files
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: ./.github/actions/slack-alert
+        with:
+          slack_channel_id: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }}
+          slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
+          color: warning
+          message: |
+            ⚠️ GraphQL Sync found ${{ needs.update_graphql_files.outputs.ignored-count }} ignored change types: ${{ needs.update_graphql_files.outputs.ignored-types }}
+
+            These change types are not in CHANGES_TO_REPORT and were silently ignored. Consider reviewing if they should be added to the changelog.
+
+            See workflow run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}