Comfy-Org · snomiao · Oct 2, 2025
diff --git a/.github/workflows/README.md b/.github/workflows/README.md
@@ -0,0 +1,88 @@
+# GitHub Workflows Documentation
+
+## Naming Convention
+
+All workflow files follow a consistent naming pattern for improved organization and discoverability.
+
+### File Naming Format
+
+```
+<prefix>-<descriptive-name>.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
+
+### 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` |
+| `pr-` | PR Automation | PR-specific workflows triggered by labels | `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` |
+
+## Workflow Organization
+
+### 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)
+
+### 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
+
+### 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
diff --git a/.github/workflows/validate-json.yaml → .github/workflows/ci-json-validation.yaml b/.github/workflows/validate-json.yaml → .github/workflows/ci-json-validation.yaml
@@ -1,4 +1,4 @@
-name: Validate JSON
+name: JSON Validation CI
 
 on:
   push:

diff --git a/.github/workflows/lint-and-format.yaml → .github/workflows/ci-lint-format.yaml b/.github/workflows/lint-and-format.yaml → .github/workflows/ci-lint-format.yaml
@@ -1,4 +1,4 @@
-name: Lint and Format
+name: Lint Format CI
 
 on:
   pull_request:

diff --git a/.github/workflows/devtools-python-check.yaml → .github/workflows/ci-python-validation.yaml b/.github/workflows/devtools-python-check.yaml → .github/workflows/ci-python-validation.yaml
@@ -1,4 +1,4 @@
-name: Devtools Python Check
+name: Python Validation CI
 
 on:
   pull_request:

diff --git a/...workflows/pr-playwright-deploy-forks.yaml → .github/workflows/ci-tests-e2e-forks.yaml b/...workflows/pr-playwright-deploy-forks.yaml → .github/workflows/ci-tests-e2e-forks.yaml
@@ -1,8 +1,10 @@
-name: PR Playwright Deploy (Forks)
+name: Tests E2E Forks CI
+
+# Deploys test results from forked PRs (forks can't access deployment secrets)
 
 on:
   workflow_run:
-    workflows: ["Tests CI"]
+    workflows: ["Tests E2E CI"]
     types: [requested, completed]
 
 env:

diff --git a/.github/workflows/tests-ci.yaml → .github/workflows/ci-tests-e2e.yaml b/.github/workflows/tests-ci.yaml → .github/workflows/ci-tests-e2e.yaml
@@ -1,4 +1,4 @@
-name: Tests CI
+name: Tests E2E CI
 
 on:
   push:

diff --git a/.../workflows/pr-storybook-deploy-forks.yaml → ...b/workflows/ci-tests-storybook-forks.yaml b/.../workflows/pr-storybook-deploy-forks.yaml → ...b/workflows/ci-tests-storybook-forks.yaml
@@ -1,8 +1,10 @@
-name: PR Storybook Deploy (Forks)
+name: Tests Storybook Forks CI
+
+# Deploys Storybook previews from forked PRs (forks can't access deployment secrets)
 
 on:
   workflow_run:
-    workflows: ['Storybook and Chromatic CI']
+    workflows: ['Tests Storybook CI']
     types: [requested, completed]
 
 env:

diff --git a/...workflows/storybook-and-chromatic-ci.yaml → .github/workflows/ci-tests-storybook.yaml b/...workflows/storybook-and-chromatic-ci.yaml → .github/workflows/ci-tests-storybook.yaml
@@ -1,4 +1,4 @@
-name: Storybook and Chromatic CI
+name: Tests Storybook CI
 
 # - [Automate Chromatic with GitHub Actions • Chromatic docs]( https://www.chromatic.com/docs/github-actions/ )
 

diff --git a/.github/workflows/vitest-tests.yaml → .github/workflows/ci-tests-unit.yaml b/.github/workflows/vitest-tests.yaml → .github/workflows/ci-tests-unit.yaml
@@ -1,4 +1,4 @@
-name: Vitest Tests
+name: Tests Unit CI
 
 on:
   push:

diff --git a/.github/workflows/update-locales.yaml → .github/workflows/i18n-update-core.yaml b/.github/workflows/update-locales.yaml → .github/workflows/i18n-update-core.yaml
@@ -1,4 +1,4 @@
-name: Update Locales
+name: i18n Update Core
 
 on:
   # Manual dispatch for urgent translation updates  

diff --git a/...les-for-given-custom-node-repository.yaml → ...b/workflows/i18n-update-custom-nodes.yaml b/...les-for-given-custom-node-repository.yaml → ...b/workflows/i18n-update-custom-nodes.yaml
@@ -1,4 +1,4 @@
-name: Update Locales for given custom node repository
+name: i18n Update Custom Nodes
 
 on:
   workflow_dispatch:

diff --git a/...lows/update-node-definitions-locales.yaml → .github/workflows/i18n-update-nodes.yaml b/...lows/update-node-definitions-locales.yaml → .github/workflows/i18n-update-nodes.yaml
@@ -1,4 +1,4 @@
-name: Update Node Definitions Locales
+name: i18n Update Nodes
 
 on:
   workflow_dispatch:

diff --git a/.github/workflows/auto-backport.yaml → .github/workflows/pr-backport.yaml b/.github/workflows/auto-backport.yaml → .github/workflows/pr-backport.yaml
@@ -1,4 +1,4 @@
-name: Auto Backport
+name: PR Backport
 
 on:
   pull_request_target:

diff --git a/.github/workflows/claude-pr-review.yml → .github/workflows/pr-claude-review.yaml b/.github/workflows/claude-pr-review.yml → .github/workflows/pr-claude-review.yaml
@@ -1,4 +1,4 @@
-name: Claude PR Review
+name: PR Claude Review
 
 permissions:
   contents: read

diff --git a/...flows/update-playwright-expectations.yaml → ...ub/workflows/pr-playwright-snapshots.yaml b/...flows/update-playwright-expectations.yaml → ...ub/workflows/pr-playwright-snapshots.yaml
@@ -1,5 +1,5 @@
 # Setting test expectation screenshots for Playwright
-name: Update Playwright Expectations
+name: PR Playwright Snapshots
 
 on:
   pull_request:

diff --git a/.github/workflows/create-release-branch.yaml → .github/workflows/release-branch-create.yaml b/.github/workflows/create-release-branch.yaml → .github/workflows/release-branch-create.yaml
@@ -1,4 +1,4 @@
-name: Create Release Branch
+name: Release Branch Create
 
 on:
   pull_request:

diff --git a/.github/workflows/create-release-draft.yaml → .github/workflows/release-draft-create.yaml b/.github/workflows/create-release-draft.yaml → .github/workflows/release-draft-create.yaml
@@ -1,4 +1,4 @@
-name: Create Release Draft
+name: Release Draft Create
 
 on:
   pull_request:
@@ -126,7 +126,7 @@ jobs:
 
   publish_types:
     needs: build
-    uses: ./.github/workflows/publish-frontend-types.yaml
+    uses: ./.github/workflows/release-npm-types.yaml
     with:
       version: ${{ needs.build.outputs.version }}
       ref: ${{ github.event.pull_request.merge_commit_sha }}

diff --git a/...hub/workflows/publish-frontend-types.yaml → .github/workflows/release-npm-types.yaml b/...hub/workflows/publish-frontend-types.yaml → .github/workflows/release-npm-types.yaml
@@ -1,4 +1,4 @@
-name: Publish Frontend Types
+name: Release NPM Types
 
 on:
   workflow_dispatch:

diff --git a/...ub/workflows/create-dev-pypi-package.yaml → .github/workflows/release-pypi-dev.yaml b/...ub/workflows/create-dev-pypi-package.yaml → .github/workflows/release-pypi-dev.yaml
@@ -1,4 +1,4 @@
-name: Create Dev PyPI Package
+name: Release PyPI Dev
 
 on:
   workflow_dispatch:

diff --git a/.github/workflows/version-bump.yaml → .github/workflows/release-version-bump.yaml b/.github/workflows/version-bump.yaml → .github/workflows/release-version-bump.yaml
@@ -1,4 +1,4 @@
-name: Version Bump
+name: Release Version Bump
 
 on:
   workflow_dispatch:

diff --git a/.github/workflows/update-electron-types.yaml → .github/workflows/types-electron-api.yaml b/.github/workflows/update-electron-types.yaml → .github/workflows/types-electron-api.yaml
@@ -1,4 +1,4 @@
-name: Update Electron Types
+name: Types Electron API
 
 on:
   workflow_dispatch:

diff --git a/...ows/update-comfyui-manager-api-types.yaml → .github/workflows/types-manager-api.yaml b/...ows/update-comfyui-manager-api-types.yaml → .github/workflows/types-manager-api.yaml
@@ -1,4 +1,4 @@
-name: Update ComfyUI-Manager API Types
+name: Types Manager API
 
 on:
   # Manual trigger

diff --git a/...lows/update-comfy-registry-api-types.yaml → .github/workflows/types-registry-api.yaml b/...lows/update-comfy-registry-api-types.yaml → .github/workflows/types-registry-api.yaml
@@ -1,4 +1,4 @@
-name: Update Comfy Registry API Types
+name: Types Registry API
 
 on:
   # Manual trigger