diff --git a/.github/workflows/README.md b/.github/workflows/README.md new file mode 100644 index 0000000000..dd072da28b --- /dev/null +++ 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 + +``` +-.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 \ No newline at end of file diff --git a/.github/workflows/validate-json.yaml b/.github/workflows/ci-json-validation.yaml similarity index 90% rename from .github/workflows/validate-json.yaml rename to .github/workflows/ci-json-validation.yaml index 2986d23ed1..10475412f5 100644 --- a/.github/workflows/validate-json.yaml +++ b/.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 b/.github/workflows/ci-lint-format.yaml similarity index 99% rename from .github/workflows/lint-and-format.yaml rename to .github/workflows/ci-lint-format.yaml index 1f20ab92ed..76478adef7 100644 --- a/.github/workflows/lint-and-format.yaml +++ b/.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 b/.github/workflows/ci-python-validation.yaml similarity index 94% rename from .github/workflows/devtools-python-check.yaml rename to .github/workflows/ci-python-validation.yaml index f0893e99d1..44ab4fcbb0 100644 --- a/.github/workflows/devtools-python-check.yaml +++ b/.github/workflows/ci-python-validation.yaml @@ -1,4 +1,4 @@ -name: Devtools Python Check +name: Python Validation CI on: pull_request: diff --git a/.github/workflows/pr-playwright-deploy-forks.yaml b/.github/workflows/ci-tests-e2e-forks.yaml similarity index 96% rename from .github/workflows/pr-playwright-deploy-forks.yaml rename to .github/workflows/ci-tests-e2e-forks.yaml index 660fee77fa..4b1bebc1c4 100644 --- a/.github/workflows/pr-playwright-deploy-forks.yaml +++ b/.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 b/.github/workflows/ci-tests-e2e.yaml similarity index 99% rename from .github/workflows/tests-ci.yaml rename to .github/workflows/ci-tests-e2e.yaml index 1e069ea11f..582c8374e9 100644 --- a/.github/workflows/tests-ci.yaml +++ b/.github/workflows/ci-tests-e2e.yaml @@ -1,4 +1,4 @@ -name: Tests CI +name: Tests E2E CI on: push: diff --git a/.github/workflows/pr-storybook-deploy-forks.yaml b/.github/workflows/ci-tests-storybook-forks.yaml similarity index 95% rename from .github/workflows/pr-storybook-deploy-forks.yaml rename to .github/workflows/ci-tests-storybook-forks.yaml index da27867c47..2d54547a16 100644 --- a/.github/workflows/pr-storybook-deploy-forks.yaml +++ b/.github/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/.github/workflows/storybook-and-chromatic-ci.yaml b/.github/workflows/ci-tests-storybook.yaml similarity index 99% rename from .github/workflows/storybook-and-chromatic-ci.yaml rename to .github/workflows/ci-tests-storybook.yaml index bfac965306..c98ca48706 100644 --- a/.github/workflows/storybook-and-chromatic-ci.yaml +++ b/.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 b/.github/workflows/ci-tests-unit.yaml similarity index 98% rename from .github/workflows/vitest-tests.yaml rename to .github/workflows/ci-tests-unit.yaml index 46155d9121..7d66b884db 100644 --- a/.github/workflows/vitest-tests.yaml +++ b/.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 b/.github/workflows/i18n-update-core.yaml similarity index 99% rename from .github/workflows/update-locales.yaml rename to .github/workflows/i18n-update-core.yaml index 6ee0933121..91332feace 100644 --- a/.github/workflows/update-locales.yaml +++ b/.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/.github/workflows/update-locales-for-given-custom-node-repository.yaml b/.github/workflows/i18n-update-custom-nodes.yaml similarity index 99% rename from .github/workflows/update-locales-for-given-custom-node-repository.yaml rename to .github/workflows/i18n-update-custom-nodes.yaml index ec085eab59..0178d524ee 100644 --- a/.github/workflows/update-locales-for-given-custom-node-repository.yaml +++ b/.github/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/.github/workflows/update-node-definitions-locales.yaml b/.github/workflows/i18n-update-nodes.yaml similarity index 97% rename from .github/workflows/update-node-definitions-locales.yaml rename to .github/workflows/i18n-update-nodes.yaml index b063159ddf..aef7b95b63 100644 --- a/.github/workflows/update-node-definitions-locales.yaml +++ b/.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 b/.github/workflows/pr-backport.yaml similarity index 99% rename from .github/workflows/auto-backport.yaml rename to .github/workflows/pr-backport.yaml index 20eadc0c9e..13e6dd74e8 100644 --- a/.github/workflows/auto-backport.yaml +++ b/.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 b/.github/workflows/pr-claude-review.yaml similarity index 99% rename from .github/workflows/claude-pr-review.yml rename to .github/workflows/pr-claude-review.yaml index 08ad707274..75acd59e2c 100644 --- a/.github/workflows/claude-pr-review.yml +++ b/.github/workflows/pr-claude-review.yaml @@ -1,4 +1,4 @@ -name: Claude PR Review +name: PR Claude Review permissions: contents: read diff --git a/.github/workflows/update-playwright-expectations.yaml b/.github/workflows/pr-playwright-snapshots.yaml similarity index 98% rename from .github/workflows/update-playwright-expectations.yaml rename to .github/workflows/pr-playwright-snapshots.yaml index 82b99baa87..73f37201de 100644 --- a/.github/workflows/update-playwright-expectations.yaml +++ b/.github/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 b/.github/workflows/release-branch-create.yaml similarity index 99% rename from .github/workflows/create-release-branch.yaml rename to .github/workflows/release-branch-create.yaml index 7891a845db..992e779ddb 100644 --- a/.github/workflows/create-release-branch.yaml +++ b/.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 b/.github/workflows/release-draft-create.yaml similarity index 98% rename from .github/workflows/create-release-draft.yaml rename to .github/workflows/release-draft-create.yaml index c359e3da49..240a89f1f2 100644 --- a/.github/workflows/create-release-draft.yaml +++ b/.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/.github/workflows/publish-frontend-types.yaml b/.github/workflows/release-npm-types.yaml similarity index 99% rename from .github/workflows/publish-frontend-types.yaml rename to .github/workflows/release-npm-types.yaml index 142a22a93c..23f0cc016b 100644 --- a/.github/workflows/publish-frontend-types.yaml +++ b/.github/workflows/release-npm-types.yaml @@ -1,4 +1,4 @@ -name: Publish Frontend Types +name: Release NPM Types on: workflow_dispatch: diff --git a/.github/workflows/create-dev-pypi-package.yaml b/.github/workflows/release-pypi-dev.yaml similarity index 98% rename from .github/workflows/create-dev-pypi-package.yaml rename to .github/workflows/release-pypi-dev.yaml index b592a8371e..88675e82e3 100644 --- a/.github/workflows/create-dev-pypi-package.yaml +++ b/.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 b/.github/workflows/release-version-bump.yaml similarity index 98% rename from .github/workflows/version-bump.yaml rename to .github/workflows/release-version-bump.yaml index 4073729db8..c9573c6cd1 100644 --- a/.github/workflows/version-bump.yaml +++ b/.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 b/.github/workflows/types-electron-api.yaml similarity index 98% rename from .github/workflows/update-electron-types.yaml rename to .github/workflows/types-electron-api.yaml index 45d959b86d..b8595d1cb0 100644 --- a/.github/workflows/update-electron-types.yaml +++ b/.github/workflows/types-electron-api.yaml @@ -1,4 +1,4 @@ -name: Update Electron Types +name: Types Electron API on: workflow_dispatch: diff --git a/.github/workflows/update-comfyui-manager-api-types.yaml b/.github/workflows/types-manager-api.yaml similarity index 99% rename from .github/workflows/update-comfyui-manager-api-types.yaml rename to .github/workflows/types-manager-api.yaml index 7e307dfda6..af2cb2f9b5 100644 --- a/.github/workflows/update-comfyui-manager-api-types.yaml +++ b/.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/.github/workflows/update-comfy-registry-api-types.yaml b/.github/workflows/types-registry-api.yaml similarity index 99% rename from .github/workflows/update-comfy-registry-api-types.yaml rename to .github/workflows/types-registry-api.yaml index 41a4db9ab9..5cfd2fd7a4 100644 --- a/.github/workflows/update-comfy-registry-api-types.yaml +++ b/.github/workflows/types-registry-api.yaml @@ -1,4 +1,4 @@ -name: Update Comfy Registry API Types +name: Types Registry API on: # Manual trigger