From ba2039c8f9cb0d123c981e5af2e9805b37c2dfa7 Mon Sep 17 00:00:00 2001 From: Ryuya Date: Sun, 4 Oct 2026 12:26:35 -0700 Subject: [PATCH] docs: clarify update workflow recovery --- .github/workflows/typescript-update.yml | 9 +++------ .github/workflows/weekly-update.yml | 9 +++------ docs/OPERATIONS.md | 17 ++++++++++++++++- 3 files changed, 22 insertions(+), 13 deletions(-) diff --git a/.github/workflows/typescript-update.yml b/.github/workflows/typescript-update.yml index c95ef27..700a53b 100644 --- a/.github/workflows/typescript-update.yml +++ b/.github/workflows/typescript-update.yml @@ -86,17 +86,14 @@ jobs: UPDATE_WORKFLOW_STEPS: ${{ toJSON(steps) }} run: node scripts/update-diagnostics.mjs report - # By GitHub design, PRs opened with the default GITHUB_TOKEN don't trigger - # any pull_request workflow (validate / test-typescript / package-dry-run). - # Set AUTOMATION_TOKEN (a fine-grained PAT or GitHub App token) to run CI - # on bot PRs too. + # A separate token lets PR checks run without manual approval. - name: Warn when AUTOMATION_TOKEN is not configured env: AUTOMATION_TOKEN: ${{ secrets.AUTOMATION_TOKEN }} run: | if [ -z "$AUTOMATION_TOKEN" ]; then - message="AUTOMATION_TOKEN is not set, so PRs created by this workflow won't run pull_request CI automatically. Register a fine-grained PAT (contents: write / pull-requests: write) as AUTOMATION_TOKEN in the repository secrets." - echo "::warning title=CI won't run on bot PRs::${message}" + message="AUTOMATION_TOKEN is not set. PR checks created with GITHUB_TOKEN require manual approval. Set AUTOMATION_TOKEN with contents: write and pull-requests: write for unattended checks." + echo "::warning title=PR checks need approval::${message}" echo "> [!WARNING]" >> "$GITHUB_STEP_SUMMARY" echo "> ${message}" >> "$GITHUB_STEP_SUMMARY" fi diff --git a/.github/workflows/weekly-update.yml b/.github/workflows/weekly-update.yml index 482ec23..6db7200 100644 --- a/.github/workflows/weekly-update.yml +++ b/.github/workflows/weekly-update.yml @@ -72,17 +72,14 @@ jobs: UPDATE_WORKFLOW_STEPS: ${{ toJSON(steps) }} run: node scripts/update-diagnostics.mjs report - # By GitHub design, PRs opened with the default GITHUB_TOKEN don't trigger - # any pull_request workflow (validate / test-typescript / package-dry-run). - # Set AUTOMATION_TOKEN (a fine-grained PAT or GitHub App token) to run CI - # on bot PRs too. + # A separate token lets PR checks run without manual approval. - name: Warn when AUTOMATION_TOKEN is not configured env: AUTOMATION_TOKEN: ${{ secrets.AUTOMATION_TOKEN }} run: | if [ -z "$AUTOMATION_TOKEN" ]; then - message="AUTOMATION_TOKEN is not set, so PRs created by this workflow won't run pull_request CI automatically. Register a fine-grained PAT (contents: write / pull-requests: write) as AUTOMATION_TOKEN in the repository secrets." - echo "::warning title=CI won't run on bot PRs::${message}" + message="AUTOMATION_TOKEN is not set. PR checks created with GITHUB_TOKEN require manual approval. Set AUTOMATION_TOKEN with contents: write and pull-requests: write for unattended checks." + echo "::warning title=PR checks need approval::${message}" echo "> [!WARNING]" >> "$GITHUB_STEP_SUMMARY" echo "> ${message}" >> "$GITHUB_STEP_SUMMARY" fi diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md index eb2668b..cd3f822 100644 --- a/docs/OPERATIONS.md +++ b/docs/OPERATIONS.md @@ -36,6 +36,19 @@ Identical inputs produce byte-identical artifacts on each supported operating sy - `libSource` records the platform package and one content hash. The update requires identical files on Linux, macOS, and Windows. - `typescriptSource` records the exact `microsoft/TypeScript` `main` commit used by proposal preparation and integration tests. Proposal artifacts are generated from that checkout's declaration corpus. +## Update workflows + +Weekly Update refreshes `web-features` and the generated declarations. TypeScript Toolchain Update refreshes the supported compiler packages and source pin, then tests the upstream integration. Both open a reviewable PR when inputs change; neither publishes a package. An unchanged snapshot can finish successfully without creating a PR. + +To check current `main`, run these commands from the repository checkout: + +```sh +gh workflow run weekly-update.yml --ref main +gh workflow run typescript-update.yml --ref main +``` + +The workflows use `AUTOMATION_TOKEN` so PR checks can start automatically. A fine-grained PAT needs `contents: write` and `pull-requests: write` access to this repository. Without that secret, the default `GITHUB_TOKEN` needs repository permission to create PRs, and its PR checks require manual approval. Approve pending workflows before merging. See [GitHub's token behavior](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow). + ## Failed updates Weekly data and TypeScript toolchain updates save an `update-diagnostics` workflow artifact, including command logs, `summary.md`, and `summary.json`. The job summary shows the failed step, candidate input pins, and added, removed, or changed compat keys. Reports use the input dataset even if generation fails; existing derived files are not evidence that the candidate passed. @@ -44,4 +57,6 @@ For registry drift, inspect each named compat key and its upstream declaration b For a TypeScript layout change, update the integration adapter and its fixtures. Keep proposal generation pinned to the recorded commit. Run `npm run validate`, then run `npm run test:typescript:gate` against that commit before retrying the toolchain workflow. -Failed update jobs do not create pull requests. Repair the cause and rerun the workflow. Diagnostic collection does not change the release gates or publish a package. +Failed update jobs do not create pull requests. After merging a fix, start a new run on `main` using the commands above. GitHub's [Re-run jobs](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs) uses the original commit, so it can repeat a failure that is already fixed on `main`. Use it for a transient failure that does not require a repository change. + +Diagnostic collection does not change the release gates or publish a package.