|
| 1 | +# GitHub Workflows Documentation |
| 2 | + |
| 3 | +## Naming Convention |
| 4 | + |
| 5 | +All workflow files follow a consistent naming pattern for improved organization and discoverability. |
| 6 | + |
| 7 | +### File Naming Format |
| 8 | + |
| 9 | +``` |
| 10 | +<prefix>-<descriptive-name>.yaml |
| 11 | +``` |
| 12 | + |
| 13 | +**Rules:** |
| 14 | +1. Use `.yaml` extension consistently (not `.yml`) |
| 15 | +2. Use lowercase letters only |
| 16 | +3. Use hyphens (`-`) as word separators |
| 17 | +4. Start with a category prefix (see below) |
| 18 | +5. Follow prefix with a descriptive name that clearly indicates the workflow's purpose |
| 19 | + |
| 20 | +### Category Prefixes |
| 21 | + |
| 22 | +| Prefix | Category | Purpose | Example | |
| 23 | +|--------|----------|---------|---------| |
| 24 | +| `ci-` | Continuous Integration | Testing, linting, validation workflows | `ci-tests-e2e.yaml` | |
| 25 | +| `release-` | Release Management | Version bumps, release branches, release drafts | `release-version-bump.yaml` | |
| 26 | +| `pr-` | PR Automation | PR-specific workflows triggered by labels | `pr-claude-review.yaml` | |
| 27 | +| `types-` | Type Generation | TypeScript type generation and updates | `types-registry-api.yaml` | |
| 28 | +| `i18n-` | Internationalization | Locale and translation updates | `i18n-update-core.yaml` | |
| 29 | + |
| 30 | +## Workflow Organization |
| 31 | + |
| 32 | +### Test Workflows (`ci-tests-*`) |
| 33 | +- `ci-tests-e2e.yaml` - End-to-end testing with Playwright |
| 34 | +- `ci-tests-unit.yaml` - Unit and component testing with Vitest |
| 35 | +- `ci-tests-storybook.yaml` - Storybook build and visual regression testing |
| 36 | +- `ci-tests-*-forks.yaml` - Fork-safe deployment workflows (deploy results without exposing secrets) |
| 37 | + |
| 38 | +### PR Label Workflows (`pr-*`) |
| 39 | +These workflows are triggered when specific labels are added to PRs: |
| 40 | + |
| 41 | +| Workflow | Trigger Label | Purpose | |
| 42 | +|----------|---------------|---------| |
| 43 | +| `pr-backport.yaml` | `needs-backport` | Cherry-pick PRs to release branches | |
| 44 | +| `pr-claude-review.yaml` | `claude-review` | AI-powered code review | |
| 45 | +| `pr-playwright-snapshots.yaml` | `New Browser Test Expectations` | Update visual test snapshots | |
| 46 | + |
| 47 | +## Workflow Triggers |
| 48 | + |
| 49 | +### Common Trigger Patterns |
| 50 | + |
| 51 | +| Trigger Type | Use Case | Example | |
| 52 | +|--------------|----------|---------| |
| 53 | +| `push` to main/master | Production CI/CD | Deploy to production | |
| 54 | +| `pull_request` | PR validation | Run tests, linting | |
| 55 | +| `workflow_dispatch` | Manual execution | On-demand deployments | |
| 56 | +| `repository_dispatch` | External triggers | API type updates | |
| 57 | +| `workflow_run` | Chain workflows | Fork deployments | |
| 58 | +| `schedule` | Periodic tasks | Nightly builds | |
| 59 | +| Label added | Conditional actions | Review requests, snapshots | |
| 60 | + |
| 61 | +### Branch Protection Patterns |
| 62 | + |
| 63 | +- **Main branches**: `main`, `master` |
| 64 | +- **Release branches**: `core/**`, `release/**` |
| 65 | +- **Development branches**: `dev/**`, `develop/**` |
| 66 | +- **Desktop branches**: `desktop/**` |
| 67 | +- **WIP exclusion**: `!**wip/**`, `!wip/**` |
| 68 | + |
| 69 | +## Best Practices |
| 70 | + |
| 71 | +1. **Consistency**: Always use the naming convention for new workflows |
| 72 | +2. **Documentation**: Update this README when adding new prefixes or patterns |
| 73 | +3. **Permissions**: Use minimal required permissions for security |
| 74 | +4. **Caching**: Leverage GitHub Actions cache for dependencies and build artifacts |
| 75 | +5. **Concurrency**: Use concurrency groups to prevent duplicate runs |
| 76 | +6. **Secrets**: Never hardcode secrets; use GitHub Secrets |
| 77 | +7. **Fork Support**: Consider fork limitations when designing workflows |
| 78 | +8. **Error Handling**: Include proper error handling and status checks |
| 79 | +9. **Reusability**: Use workflow_call for shared logic across workflows |
| 80 | + |
| 81 | +## External Dependencies |
| 82 | + |
| 83 | +- **Cloudflare Pages**: Deployment platform for previews and test reports |
| 84 | +- **Chromatic**: Visual regression testing for Storybook |
| 85 | +- **OpenAI API**: Translation generation for i18n workflows |
| 86 | +- **PyPI**: Python package distribution |
| 87 | +- **npm Registry**: TypeScript types distribution |
| 88 | +- **Claude API**: AI code review |
0 commit comments