From ea4686a52cc36b8ee0cf6a2fb28de16e8d23cc4e Mon Sep 17 00:00:00 2001 From: snomiao Date: Mon, 13 Oct 2025 23:50:51 +0000 Subject: [PATCH] [docs] add workflow comments and simplify README to prevent staleness MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add descriptive comments to key workflow files explaining purpose and triggers - Simplify workflows README.md to focus on naming convention only - Remove detailed workflow descriptions that can get out of date - Point users to individual workflow files for current documentation Addresses review feedback: documentation can get out of date quickly, put comments into workflows themselves with single example in README. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .github/workflows/README.md | 95 +++------------------ .github/workflows/ci-json-validation.yaml | 2 +- .github/workflows/ci-tests-e2e.yaml | 4 + .github/workflows/ci-tests-storybook.yaml | 4 +- .github/workflows/ci-tests-unit.yaml | 3 + .github/workflows/i18n-update-core.yaml | 3 + .github/workflows/pr-claude-review.yaml | 3 + .github/workflows/release-version-bump.yaml | 3 + 8 files changed, 32 insertions(+), 85 deletions(-) diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 54ab5bcbe..f0fe1f3c2 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -1,92 +1,21 @@ -# GitHub Workflows Documentation +# GitHub Workflows ## Naming Convention -All workflow files follow a consistent naming pattern for improved organization and discoverability. - -### File Naming Format - -``` --.yaml -``` - -**Rules:** -1. Use `.yaml` extension consistently (not `.yml`) -2. Use lowercase letters only -3. Use hyphens (`-`) as word separators -4. Start with a category prefix (see below) -5. Follow prefix with a descriptive name that clearly indicates the workflow's purpose +Workflow files follow a consistent naming pattern: `-.yaml` ### Category Prefixes -| Prefix | Category | Purpose | Example | -|--------|----------|---------|---------| -| `ci-` | Continuous Integration | Testing, linting, validation workflows | `ci-tests-e2e.yaml` | -| `release-` | Release Management | Version bumps, release branches, release drafts | `release-version-bump.yaml` | -| `ci-` | Continuous Integration | Testing, linting, validation workflows | `ci-tests-e2e.yaml` | -| `release-` | Release Management | Version bumps, release branches, release drafts | `release-version-bump.yaml` | -| `pr-` | PR Automation | PR-specific workflows triggered by labels or comments | `pr-claude-review.yaml` | -| `types-` | Type Generation | TypeScript type generation and updates | `types-registry-api.yaml` | -| `i18n-` | Internationalization | Locale and translation updates | `i18n-update-core.yaml` | +| Prefix | Purpose | Example | +|--------|---------|---------| +| `ci-` | Testing, linting, validation | `ci-tests-e2e.yaml` | +| `release-` | Version management, publishing | `release-version-bump.yaml` | +| `pr-` | PR automation (triggered by labels) | `pr-claude-review.yaml` | +| `types-` | TypeScript type generation | `types-registry-api.yaml` | +| `i18n-` | Internationalization updates | `i18n-update-core.yaml` | -## Workflow Organization +## Documentation -### Test Workflows (`ci-tests-*`) -- `ci-tests-e2e.yaml` - End-to-end testing with Playwright -- `ci-tests-unit.yaml` - Unit and component testing with Vitest -- `ci-tests-storybook.yaml` - Storybook build and visual regression testing -- `ci-tests-*-forks.yaml` - Fork-safe deployment workflows (deploy results without exposing secrets) +Each workflow file contains comments explaining its purpose, triggers, and behavior. For specific details about what each workflow does, refer to the comments at the top of each `.yaml` file. -### PR Label Workflows (`pr-*`) -These workflows are triggered when specific labels are added to PRs: - -| Workflow | Trigger Label | Purpose | -|----------|---------------|---------| -| `pr-backport.yaml` | `needs-backport` | Cherry-pick PRs to release branches | -| `pr-claude-review.yaml` | `claude-review` | AI-powered code review | -| `pr-playwright-snapshots.yaml` | `New Browser Test Expectations` | Update visual test snapshots | - -## Workflow Triggers - -For more details on workflow triggers, see [GitHub's workflow trigger documentation](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows). - -### Common Trigger Patterns - -| Trigger Type | Use Case | Example | -|--------------|----------|---------| -| `push` to main/master | Production CI/CD | Deploy to production | -| `pull_request` | PR validation | Run tests, linting | -| `workflow_dispatch` | Manual execution | On-demand deployments | -| `repository_dispatch` | External triggers | API type updates | -| `workflow_run` | Chain workflows | Fork deployments | -| `schedule` | Periodic tasks | Nightly builds | -| Label added | Conditional actions | Review requests, snapshots | - -### Branch Protection Patterns - -- **Main branches**: `main`, `master` -- **Release branches**: `core/**`, `release/**` -- **Development branches**: `dev/**`, `develop/**` -- **Desktop branches**: `desktop/**` -- **WIP exclusion**: `!**wip/**`, `!wip/**` - -## Best Practices - -1. **Consistency**: Always use the naming convention for new workflows -2. **Documentation**: Update this README when adding new prefixes or patterns -3. **Permissions**: Use minimal required permissions for security -4. **Caching**: Leverage GitHub Actions cache for dependencies and build artifacts -5. **Concurrency**: Use concurrency groups to prevent duplicate runs -6. **Secrets**: Never hardcode secrets; use GitHub Secrets -7. **Fork Support**: Consider fork limitations when designing workflows -8. **Error Handling**: Include proper error handling and status checks -9. **Reusability**: Use workflow_call for shared logic across workflows - -## External Dependencies - -- **Cloudflare Pages**: Deployment platform for previews and test reports -- **Chromatic**: Visual regression testing for Storybook -- **OpenAI API**: Translation generation for i18n workflows -- **PyPI**: Python package distribution -- **npm Registry**: TypeScript types distribution -- **Claude API**: AI code review \ No newline at end of file +For GitHub Actions documentation, see [Events that trigger workflows](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows). \ No newline at end of file diff --git a/.github/workflows/ci-json-validation.yaml b/.github/workflows/ci-json-validation.yaml index 0d83316e0..a1d3bf369 100644 --- a/.github/workflows/ci-json-validation.yaml +++ b/.github/workflows/ci-json-validation.yaml @@ -1,4 +1,4 @@ -name: CI - JSON Validation +name: "CI: JSON Validation" on: push: diff --git a/.github/workflows/ci-tests-e2e.yaml b/.github/workflows/ci-tests-e2e.yaml index a457538f8..eb8f04ab3 100644 --- a/.github/workflows/ci-tests-e2e.yaml +++ b/.github/workflows/ci-tests-e2e.yaml @@ -1,5 +1,9 @@ name: Tests E2E CI +# End-to-end testing with Playwright across multiple browsers and configurations +# Runs on main branches and PRs, skips WIP branches +# Generates test reports and deploys them to Cloudflare Pages for review + on: push: branches: [main, master, core/*, desktop/*] diff --git a/.github/workflows/ci-tests-storybook.yaml b/.github/workflows/ci-tests-storybook.yaml index c98ca4870..7960219f6 100644 --- a/.github/workflows/ci-tests-storybook.yaml +++ b/.github/workflows/ci-tests-storybook.yaml @@ -1,6 +1,8 @@ name: Tests Storybook CI -# - [Automate Chromatic with GitHub Actions • Chromatic docs]( https://www.chromatic.com/docs/github-actions/ ) +# Builds Storybook and runs visual regression testing via Chromatic +# Deploys Storybook previews to Cloudflare Pages for PR review +# Reference: https://www.chromatic.com/docs/github-actions/ on: workflow_dispatch: # Allow manual triggering diff --git a/.github/workflows/ci-tests-unit.yaml b/.github/workflows/ci-tests-unit.yaml index 778ab15d3..775d14ef0 100644 --- a/.github/workflows/ci-tests-unit.yaml +++ b/.github/workflows/ci-tests-unit.yaml @@ -1,5 +1,8 @@ name: Tests Unit CI +# Unit and component testing with Vitest +# Runs on main branches and PRs, skips WIP branches + on: push: branches: [main, master, dev*, core/*, desktop/*] diff --git a/.github/workflows/i18n-update-core.yaml b/.github/workflows/i18n-update-core.yaml index fc8b0bd06..da1737480 100644 --- a/.github/workflows/i18n-update-core.yaml +++ b/.github/workflows/i18n-update-core.yaml @@ -1,5 +1,8 @@ name: i18n Update Core +# Generates and updates translations for core ComfyUI components using OpenAI +# Runs manually or automatically on version-bump PRs to keep translations current + on: # Manual dispatch for urgent translation updates workflow_dispatch: diff --git a/.github/workflows/pr-claude-review.yaml b/.github/workflows/pr-claude-review.yaml index e6b30b059..292fe676c 100644 --- a/.github/workflows/pr-claude-review.yaml +++ b/.github/workflows/pr-claude-review.yaml @@ -1,5 +1,8 @@ name: PR Claude Review +# AI-powered code review triggered by adding the "claude-review" label to a PR +# Provides comprehensive analysis of code changes, architecture, and security + permissions: contents: read pull-requests: write diff --git a/.github/workflows/release-version-bump.yaml b/.github/workflows/release-version-bump.yaml index c9573c6cd..d0b530691 100644 --- a/.github/workflows/release-version-bump.yaml +++ b/.github/workflows/release-version-bump.yaml @@ -1,5 +1,8 @@ name: Release Version Bump +# Manual workflow to increment package version and create version commit +# Supports semantic versioning (patch, minor, major) and pre-release versions + on: workflow_dispatch: inputs: