Merge pull request #46206 from github/repo-sync

Repo sync

Author: docs-bot

.devcontainer/Dockerfile

@@ -1,3 +1,4 @@
-# To find available Node images, see https://mcr.microsoft.com/en-us/product/devcontainers/javascript-node/tags
+# 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:c6c609fc8c4e9418991aae295debc1f4f94f000f4cc7ca5531446f1ea8258056
+FROM mcr.microsoft.com/devcontainers/javascript-node:dev-24-bookworm@sha256:c39e4aaf0c7c4da594f845aeb98d37510343bff178b320a6f7e9e2e95ca7957e

.github/CODEOWNERS

@@ -1,10 +1,4 @@
-# Order is important. The LAST matching pattern has the MOST precedence.
-# gitignore style patterns are used, not globs.
-# https://docs.github.com/articles/about-codeowners
-# https://git-scm.com/docs/gitignore
+# Last matching pattern wins.
+# Patterns use gitignore syntax, not glob syntax.
 
-# Site Policy
 content/site-policy/ @github/site-policy-admins
-
-# Requires review of #actions-oidc-integration, docs-engineering/issues/1506
-# content/actions/deployment/security-hardening-your-deployments/** @github/oidc

.github/actions/cache-nextjs/action.yml

@@ -1,4 +1,5 @@
-# Based on https://nextjs.org/docs/pages/building-your-application/deploying/ci-build-caching#github-actions
+# Based on Next.js CI build cache guidance:
+# https://nextjs.org/docs/pages/building-your-application/deploying/ci-build-caching#github-actions
 
 name: Cache Nextjs build cache
 
@@ -11,8 +12,8 @@ runs:
       uses: actions/cache@v4
       with:
         path: ${{ github.workspace }}/.next/cache
-        # Generate a new cache whenever packages or source files change.
+        # Packages and source files both invalidate the cache.
         key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.ts', '**/*.tsx') }}
-        # If source files changed but packages didn't, rebuild from a prior cache.
+        # With matching restore-key prefixes, source-only changes restore the same-package cache.
         restore-keys: |
           ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-

.github/actions/create-workflow-failure-issue/action.yml

@@ -104,8 +104,6 @@ runs:
           --body "$body")
         echo "issue_url=$url" >> "$GITHUB_OUTPUT"
 
-        # Set the type separately, and tolerate failure. This action is itself the
-        # failure path, so losing the whole issue because issue types are unavailable
-        # or `gh` is too old (--type needs gh 2.94+) would hide the original failure.
+        # Set type separately with gh 2.94+ --type; keep the issue visible if gh or issue types lack support.
         gh issue edit "$url" --type Bug \
           || echo "Warning: could not set issue type on $url; leaving it unset."

.github/actions/labeler/labeler.ts

@@ -1,5 +1,3 @@
-/* See function main in this file for documentation */
-
 import * as coreLib from '@actions/core'
 import { type Octokit } from '@octokit/rest'
 import { CoreInject } from '@/links/scripts/action-injections'
@@ -18,7 +16,7 @@ type Options = {
   repo?: string
 }
 
-// When this file is invoked directly from action as opposed to being imported
+// Run action wiring only for direct execution, not imports from tests or other code.
 if (import.meta.url.endsWith(process.argv[1])) {
   if (!process.env.GITHUB_TOKEN) {
     throw new Error('You must set the GITHUB_TOKEN environment variable.')
@@ -33,7 +31,7 @@ if (import.meta.url.endsWith(process.argv[1])) {
     ignoreIfLabeled: boolEnvVar('IGNORE_IF_LABELED'),
   }
 
-  // labels come in comma separated from actions
+  // Actions pass comma-separated labels.
   if (typeof ADD_LABELS === 'string') {
     opts.addLabels = [...ADD_LABELS.split(',')].map((l) => l.trim())
   } else {
@@ -60,18 +58,6 @@ if (import.meta.url.endsWith(process.argv[1])) {
   main(coreLib, octokit, opts)
 }
 
-/*
- * Applies labels to an issue or pull request.
- *
- * opts:
- *  issue_number {number} id of the issue or pull request to label
- *  owner {string} owner of the repository
- *  repo {string} repository name
- *  addLabels {Array<string>} array of labels to apply
- *  removeLabels {Array<string>} array of labels to remove
- *  ignoreIfAssigned {boolean} don't apply labels if there are assignees
- *  ignoreIfLabeled {boolean} don't apply labels if there are already labels added
- */
 export default async function main(
   core: typeof coreLib | CoreInject,
   octokit: Octokit,
@@ -118,7 +104,7 @@ export default async function main(
   }
 
   if (opts.removeLabels?.length) {
-    // removing a label fails if the label isn't already applied
+    // Remove only applied labels because the API rejects missing labels.
     let appliedLabels = []
 
     try {

.github/actions/node-npm-setup/action.yml

@@ -9,8 +9,7 @@ runs:
       uses: actions/cache@v4
       id: cache-node_modules
       env:
-        # Default is 10 min, per segment, but we can make it much smaller
-        # because it's not the end of the world if the cache restore fails.
+        # Cache restore failures are acceptable, so keep the segment timeout short.
         SEGMENT_DOWNLOAD_TIMEOUT_MINS: '1'
       with:
         path: node_modules

.github/actions/precompute-pageinfo/action.yml

@@ -23,7 +23,6 @@ runs:
         INPUT_DELAY: ${{ inputs.delay }}
         INPUT_COMMAND: ${{ inputs.command }}
       run: |
-        # Generic retry function: configurable attempts and delay
         retry_command() {
           local max_attempts=${INPUT_MAX_ATTEMPTS}
           local delay=${INPUT_DELAY}

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

@@ -1,4 +1,4 @@
-# For the sake of saving time, only run this step if the test-group is one that will run tests against an Elasticsearch on localhost.
+# Callers skip this action for test groups that do not use local Elasticsearch.
 name: Set up local Elasticsearch
 
 description: Install a local Elasticsearch with version that matches prod
@@ -10,13 +10,13 @@ inputs:
   elasticsearch_version:
     description: Version of Elasticsearch to install
     required: true
-    # Make sure the version matches production and is available on Docker Hub
+    # Version must match production and be published on Docker Hub.
     default: '8.12.0'
 
 runs:
   using: 'composite'
   steps:
-    # Cache the elasticsearch image to prevent Docker Hub rate limiting
+    # Cache the Elasticsearch image to prevent Docker Hub rate limits.
     - name: Cache Docker layers
       id: cache-docker-layers
       uses: actions/cache@v4
@@ -47,8 +47,7 @@ runs:
         mkdir -p /tmp/docker-cache
         docker save -o /tmp/docker-cache/elasticsearch.tar elasticsearch:${ES_VERSION}
 
-    # Setups the Elasticsearch container
-    # Derived from https://github.com/getong/elasticsearch-action
+    # Run a single-node container with settings copied from getong/elasticsearch-action.
     - name: Run Docker container
       shell: bash
       env:
@@ -80,7 +79,6 @@ runs:
           -e discovery_type=$INPUT_DISCOVERY_TYPE \
           elasticsearch:$INPUT_ELASTICSEARCH_VERSION
 
-        # Check if Elasticsearch is up and running
         for i in {1..120}; do
           if curl --silent --fail http://localhost:9200; then
             echo "Elasticsearch is up and running"

.github/actions/setup-elasticsearch/action.yml

@@ -27,9 +27,8 @@ inputs:
 runs:
   using: composite
   steps:
-    # Build the Slack text here so the default message can be multi-line (real
-    # newlines) and conditionally include the issue link. A caller-supplied
-    # message is passed through verbatim for backward compatibility.
+    # Build default Slack text in shell so it can include real newlines and an issue link.
+    # Caller-supplied messages pass through unchanged for backward compatibility.
     - name: Build Slack message
       id: build
       shell: bash
@@ -43,10 +42,9 @@ runs:
         GIT_REF: ${{ github.ref }}
         ACTOR: ${{ github.actor }}
       run: |
-        # Escape Slack mrkdwn control chars in interpolated context fields so a
-        # crafted branch/ref (e.g. containing <!channel>) can't inject mentions.
+        # Escape generated fields so branch/ref text like <!channel> cannot inject Slack mentions.
         esc() { printf '%s' "$1" | sed -e 's/&/\&amp;/g' -e 's/</\&lt;/g' -e 's/>/\&gt;/g'; }
-        # Unique heredoc delimiter so a custom message can't collide with it.
+        # Pick a unique heredoc delimiter so custom messages cannot collide with it.
         delim="SLACK_EOF_${RANDOM}${RANDOM}"
         {
           printf 'text<<%s\n' "$delim"