Skip to content

Commit 46eaef6

Browse files
committed
feat: default workflows part of all repositories
1 parent 4190424 commit 46eaef6

File tree

1 file changed

+79
-0
lines changed

1 file changed

+79
-0
lines changed

docs/rfc/0002-core-workflows.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
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

Comments
 (0)