From 254a03aba0502476b65b6f45afd1f2a187079855 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Oct 2025 01:13:05 +0000 Subject: [PATCH] feat: Improve workflow documentation generation - Add detection for needs-backport and Release labels - Deduplicate label triggers in Quick Reference section - Generate Quick Reference dynamically from workflows - Show all label-triggered workflows with descriptions Co-authored-by: snomiao <7323030+snomiao@users.noreply.github.com> --- .github/workflows/README.md | 23 ++++++++- scripts/cicd/generate-workflow-docs.ts | 68 +++++++++++++++++++++++--- 2 files changed, 82 insertions(+), 9 deletions(-) diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 60a4267c7..e84b6beeb 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -25,11 +25,14 @@ Workflow files follow a consistent naming pattern: `-. ## Quick Reference For label-triggered workflows, add the corresponding label to a PR to trigger the workflow: -- `claude-review` - Trigger AI-powered code review -- `New Browser Test Expectations` - Update Playwright test snapshots +- `New Browser Test Expectations` - Updates Playwright test snapshots when triggered by label or comment +- `Release` - Triggers 3 workflows +- `claude-review` - AI-powered code review triggered by adding the 'claude-review' label to a PR +- `needs-backport` - Automatically backports merged PRs to release branches when 'needs-backport' label is applied For manual workflows, use the "Run workflow" button in the Actions tab. + ## Workflow Details @@ -95,6 +98,14 @@ For manual workflows, use the "Run workflow" button in the Actions tab. **Triggers:** pull_request, push +#### [`ci-workflow-docs.yaml`](./ci-workflow-docs.yaml) + +**Name:** CI: Workflow Documentation + +**Description:** Validates that workflow documentation is up-to-date with workflow files + +**Triggers:** pull_request + ### PR @@ -106,6 +117,8 @@ For manual workflows, use the "Run workflow" button in the Actions tab. **Triggers:** workflow_dispatch (manual), pull_request_target (closed, labeled) +**Label Triggers:** `needs-backport` + #### [`pr-claude-review.yaml`](./pr-claude-review.yaml) **Name:** PR: Claude Review @@ -137,6 +150,8 @@ For manual workflows, use the "Run workflow" button in the Actions tab. **Triggers:** pull_request (closed) +**Label Triggers:** `Release` + #### [`release-draft-create.yaml`](./release-draft-create.yaml) **Name:** Release Draft Create @@ -145,6 +160,8 @@ For manual workflows, use the "Run workflow" button in the Actions tab. **Triggers:** pull_request (closed) +**Label Triggers:** `Release` + #### [`release-npm-types.yaml`](./release-npm-types.yaml) **Name:** Release NPM Types @@ -234,6 +251,8 @@ For manual workflows, use the "Run workflow" button in the Actions tab. **Triggers:** pull_request (closed) +**Label Triggers:** `Release` + #### [`publish-desktop-ui.yaml`](./publish-desktop-ui.yaml) **Name:** Publish Desktop UI diff --git a/scripts/cicd/generate-workflow-docs.ts b/scripts/cicd/generate-workflow-docs.ts index fa0cde23c..c971b534b 100644 --- a/scripts/cicd/generate-workflow-docs.ts +++ b/scripts/cicd/generate-workflow-docs.ts @@ -63,6 +63,16 @@ function extractLabelTriggers(content: string, workflowData: any): string[] { } } + // Check for contains(github.event.pull_request.labels.*.name, 'label-name') pattern + const containsLabelMatches = content.matchAll( + /contains\(github\.event\.pull_request\.labels\.\*\.name,\s*['"]([^'"]+)['"]\)/gi + ) + for (const match of containsLabelMatches) { + if (!labels.includes(match[1])) { + labels.push(match[1]) + } + } + // Check for startsWith or contains patterns with label names const labelCommentMatches = content.matchAll( /startsWith\(github\.event\.comment\.body,\s*['"]([^'"]+)['"]\)/gi @@ -290,11 +300,61 @@ function generateWorkflowList(grouped: WorkflowsByPrefix): string { return markdown } +/** + * Generate quick reference for label-triggered workflows + */ +function generateQuickReference(grouped: WorkflowsByPrefix): string { + const allWorkflows = Object.values(grouped).flatMap((g) => g.workflows) + const labelWorkflows = allWorkflows.filter((w) => w.labelTriggers.length > 0) + + if (labelWorkflows.length === 0) { + return '' + } + + // Group workflows by label to avoid duplicates + const labelMap = new Map() + for (const workflow of labelWorkflows) { + for (const label of workflow.labelTriggers) { + // Skip comment-based triggers (like /update-playwright) + if (label.startsWith('/')) { + continue + } + const description = workflow.description || workflow.name + if (!labelMap.has(label)) { + labelMap.set(label, []) + } + labelMap.get(label)!.push(description) + } + } + + let markdown = '## Quick Reference\n\n' + markdown += + 'For label-triggered workflows, add the corresponding label to a PR to trigger the workflow:\n' + + // Sort labels alphabetically for consistency + const sortedLabels = Array.from(labelMap.keys()).sort() + for (const label of sortedLabels) { + const descriptions = labelMap.get(label)! + // Use the first description, or combine if multiple + const description = + descriptions.length === 1 + ? descriptions[0] + : `Triggers ${descriptions.length} workflows` + markdown += `- \`${label}\` - ${description}\n` + } + + markdown += + '\nFor manual workflows, use the "Run workflow" button in the Actions tab.\n' + + return markdown +} + /** * Generate the complete README content */ function generateReadme(grouped: WorkflowsByPrefix): string { const categoryTable = generateCategoryTable(grouped) + const quickReference = generateQuickReference(grouped) const workflowList = generateWorkflowList(grouped) return `# GitHub Workflows @@ -312,13 +372,7 @@ Workflow files follow a consistent naming pattern: \`- ${categoryTable} -## Quick Reference - -For label-triggered workflows, add the corresponding label to a PR to trigger the workflow: -- \`claude-review\` - Trigger AI-powered code review -- \`New Browser Test Expectations\` - Update Playwright test snapshots - -For manual workflows, use the "Run workflow" button in the Actions tab. +${quickReference} ## Workflow Details