|
| 1 | +# Standard default CI/CD workflows for Express.js repositories |
| 2 | + |
| 3 | +## Summary |
| 4 | + |
| 5 | +This RFC proposes a standardized set of default GitHub Actions workflows that should exist in every repository within the Express.js organization. These workflows ensure consistent validation on code pushes, pull requests, and post-merge events, along with optional compatibility and maintenance checks. The goal is to guarantee consistent quality across projects while keeping workflows lightweight and maintainable. |
| 6 | + |
| 7 | +## Motivation |
| 8 | + |
| 9 | +Currently, each repository uses its own GitHub Actions setup, or in some cases none at all. This creates: |
| 10 | + |
| 11 | +- Inconsistent behavior across repositories |
| 12 | +- Missed regressions in default branches |
| 13 | +- Repeated maintenance effort |
| 14 | +- Difficulty for new contributors to understand expectations |
| 15 | +- No consistent testing against supported Node.js versions |
| 16 | + |
| 17 | +By introducing standard workflows, we ensure: |
| 18 | + |
| 19 | +- Consistent validation across repositories |
| 20 | +- Predictable contributor experience |
| 21 | +- Continued support for Node.js LTS policy |
| 22 | +- Easier future migration to shared workflows |
| 23 | + |
| 24 | +## Detailed Explanation |
| 25 | + |
| 26 | +### Required Default Workflows |
| 27 | + |
| 28 | +| Workflow | Trigger | Required | Description | |
| 29 | +|----------|---------|----------|-------------| |
| 30 | +| **1. Push Validation** | `on: push` to non-default branches | ✅ Yes | Run tests, lint, and basic validation for fast feedback during development. | |
| 31 | +| **2. Pull Request Validation** | `on: pull_request` to `main`, `master`, or version branches | ✅ Yes | Ensures code is tested before merging. May include stricter checks than push validation. | |
| 32 | +| **3. Post-Merge / Default Branch Check** | `on: push` to `main` or release branches | ✅ Yes | Ensures the default branch remains passing after merge and runs on the official Node.js LTS version(s). | |
| 33 | +| **4. Manual Multi-Node.js Test** | `workflow_dispatch` | ✅ Yes (for core repos) | Allows manual execution of tests against multiple Node.js versions (e.g., 20, 22, 24) before releases or LTS changes. | |
| 34 | +| **5. Scheduled Compatibility Check** | `schedule:` (optional) | Optional | Runs periodically to test against latest dependencies or Node.js nightly builds. | |
| 35 | +| **6. Security / Dependency Audit** | Manual or scheduled | Optional | Runs `npm audit`, dependency checks, or license compliance. | |
| 36 | +| **7. Release Workflow** | Tag or manual trigger | Optional | Builds and publishes packages (only for repositories that publish to npm). | |
| 37 | + |
| 38 | +### Guiding Principles |
| 39 | + |
| 40 | +- Workflows should remain lightweight and fast. |
| 41 | +- No mandatory CodeQL, coverage upload, or heavy tasks. |
| 42 | +- All default workflows must be compatible with reusable workflows. |
| 43 | +- Repositories may add extra workflows if needed but should not remove core workflows. |
| 44 | + |
| 45 | +## Rationale and Alternatives |
| 46 | + |
| 47 | +| Approach | Pros | Cons | |
| 48 | +|----------|------|------| |
| 49 | +| **Proposed: Minimal Standard Workflows** | Balanced, lightweight, ensures consistency | Requires migration across repositories | |
| 50 | +| Keep current undefined setup | No effort required | Inconsistency, higher risk of breakage | |
| 51 | +| Enforce strict CI (coverage, audit, CodeQL, etc.) | Maximum protection | Too heavy for small modules, discouraging contributions | |
| 52 | + |
| 53 | +## Implementation |
| 54 | + |
| 55 | +### Affected Repositories |
| 56 | + |
| 57 | +- All repositories under the Express.js organization that use or should use CI. |
| 58 | + |
| 59 | +### Steps |
| 60 | + |
| 61 | +1. Approve this RFC. |
| 62 | +2. Create example workflow templates in `.ci-workflows/workflows/`. |
| 63 | +3. Apply to core repositories: |
| 64 | + - expressjs/express |
| 65 | + - expressjs/router |
| 66 | + - expressjs/body-parser |
| 67 | +4. Introduce shared workflows once this standard is normalized. |
| 68 | +5. Document requirements in `CONTRIBUTING.md`. |
| 69 | + |
| 70 | +## Prior Art |
| 71 | + |
| 72 | +- GitHub recommends reusable organization workflows for consistency and maintenance. |
| 73 | + |
| 74 | +## Unresolved Questions |
| 75 | + |
| 76 | +- Which Node.js versions must be tested by default? (e.g., 22 + 24 vs 18 + 20 + 22 + LTS) |
| 77 | +- Should push validation run on all branches or exclude `main`? |
| 78 | +- Naming convention for workflows (`ci.yml`, `test.yml`, `validate.yml`)? |
| 79 | +- Should `npm audit` or dependency checks be mandatory or optional? |
0 commit comments