Skip to content

Commit c08d099

Browse files
Copilothuangyiirene
Copilot
and
huangyiirene
committed
docs: add comprehensive workflow documentation
Co-authored-by: huangyiirene <7665279+huangyiirene@users.noreply.github.com>
1 parent 88e4341 commit c08d099

File tree

2 files changed

+366
-0
lines changed

2 files changed

+366
-0
lines changed

‎.github/AUTOMATION.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# 🤖 Automation Quick Reference
2+
3+
## Workflow Summary
4+
5+
| Workflow | When it runs | What it does |
6+
|----------|--------------|--------------|
7+
| 🔨 **CI** | On every push/PR | Runs tests & builds code |
8+
| 🎯 **Lint** | On every push/PR | Type checks TypeScript |
9+
| 🔒 **CodeQL** | On push/PR + weekly | Security scanning |
10+
| 📚 **Docs** | On main push (docs changes) | Deploys documentation |
11+
| 🏷️ **PR Automation** | On PR open/update | Adds labels & checks changesets |
12+
| 🧹 **Stale** | Daily | Manages inactive issues/PRs |
13+
| 📦 **Validate Deps** | On dep changes + weekly | Checks dependencies & licenses |
14+
| 🚀 **Release** | On main push | Publishes to npm |
15+
16+
## Quick Commands
17+
18+
```bash
19+
# Run tests locally
20+
pnpm --filter @objectstack/spec test
21+
22+
# Run tests with coverage
23+
pnpm --filter @objectstack/spec test:coverage
24+
25+
# Build everything
26+
pnpm run build
27+
28+
# Type check
29+
pnpm --filter @objectstack/spec exec tsc --noEmit
30+
31+
# Start docs locally
32+
pnpm docs:dev
33+
34+
# Create a changeset
35+
pnpm changeset
36+
```
37+
38+
## PR Checklist
39+
40+
Before submitting a PR:
41+
42+
- [ ] Tests pass locally
43+
- [ ] TypeScript compiles without errors
44+
- [ ] Added changeset (if user-facing changes)
45+
- [ ] Updated documentation (if needed)
46+
- [ ] Keep PR size reasonable (< 500 lines preferred)
47+
48+
## Labels
49+
50+
**Automatic labels added to PRs:**
51+
- `size/*` - Based on lines changed
52+
- `protocol:*` - Based on files changed (data/ui/system/ai)
53+
- `documentation` - Changes to docs
54+
- `ci/cd` - Changes to workflows
55+
- `dependencies` - Changes to package.json
56+
- `tests` - Changes to test files
57+
58+
**Manual labels:**
59+
- `skip-changeset` - Skip changeset requirement
60+
- `pinned` - Prevent auto-stale
61+
- `security` - Security-related changes
62+
- `work-in-progress` - PR is not ready for review
63+
64+
## Secrets Required
65+
66+
- `GITHUB_TOKEN` - ✅ Automatic
67+
- `NPM_TOKEN` - ⚠️ Configure in repo settings
68+
69+
## Monitoring
70+
71+
- **CI/CD**: [Actions tab](../../actions)
72+
- **Security**: [Security tab → Code scanning](../../security/code-scanning)
73+
- **Dependencies**: [Security tab → Dependabot](../../security/dependabot)
74+
- **Coverage**: Download from workflow artifacts
75+
76+
---
77+
78+
💡 **Tip**: All workflows use pnpm caching for faster runs!

‎.github/WORKFLOWS.md‎

Lines changed: 288 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,288 @@
1+
# GitHub Actions Workflows Documentation
2+
3+
This document describes all automated workflows configured for the ObjectStack Spec repository.
4+
5+
## Overview
6+
7+
The repository uses GitHub Actions for continuous integration, automated testing, security scanning, and maintenance tasks. Below is a comprehensive guide to all workflows.
8+
9+
## Workflows
10+
11+
### 1. CI (`.github/workflows/ci.yml`)
12+
13+
**Triggers:**
14+
- Push to `main` branch
15+
- Pull requests to `main` branch
16+
17+
**Jobs:**
18+
- **Test Job**: Runs unit tests with Vitest
19+
- Executes all tests in `packages/spec`
20+
- Generates code coverage reports
21+
- Uploads coverage reports as artifacts (retained for 30 days)
22+
23+
- **Build Job**: Builds all packages
24+
- Compiles TypeScript
25+
- Generates JSON schemas
26+
- Uploads build artifacts (retained for 30 days)
27+
28+
**Caching:** Uses pnpm store caching for faster builds
29+
30+
---
31+
32+
### 2. Lint & Type Check (`.github/workflows/lint.yml`)
33+
34+
**Triggers:**
35+
- Push to `main` branch
36+
- Pull requests to `main` branch
37+
38+
**Jobs:**
39+
- **Type Check**: Validates TypeScript type correctness
40+
- Runs `tsc --noEmit` to check for type errors
41+
- Ensures type safety across the codebase
42+
43+
**Purpose:** Catch type errors early before they reach production
44+
45+
---
46+
47+
### 3. CodeQL Security Analysis (`.github/workflows/codeql.yml`)
48+
49+
**Triggers:**
50+
- Push to `main` branch
51+
- Pull requests to `main` branch
52+
- Scheduled: Every Monday at 02:00 UTC
53+
54+
**Jobs:**
55+
- **Analyze**: Security code scanning with CodeQL
56+
- Scans JavaScript/TypeScript code
57+
- Checks for security vulnerabilities
58+
- Uses `security-and-quality` query suite
59+
- Results uploaded to GitHub Security tab
60+
61+
**Purpose:** Proactive security vulnerability detection
62+
63+
---
64+
65+
### 4. Deploy Documentation (`.github/workflows/docs.yml`)
66+
67+
**Triggers:**
68+
- Push to `main` branch (when docs/spec files change)
69+
- Manual trigger via `workflow_dispatch`
70+
71+
**Jobs:**
72+
- **Deploy**: Builds and deploys documentation
73+
- Builds protocol schemas
74+
- Compiles Next.js documentation site
75+
- Deploys to GitHub Pages
76+
77+
**Concurrency:** Prevents concurrent deployments to avoid conflicts
78+
79+
**Purpose:** Keep documentation in sync with code changes
80+
81+
---
82+
83+
### 5. PR Automation (`.github/workflows/pr-automation.yml`)
84+
85+
**Triggers:**
86+
- Pull request events: opened, synchronize, reopened, labeled, unlabeled
87+
88+
**Jobs:**
89+
90+
1. **PR Size Check**: Adds size labels to PRs
91+
- `size/xs`: 0-10 lines changed
92+
- `size/s`: 11-100 lines changed
93+
- `size/m`: 101-500 lines changed
94+
- `size/l`: 501-1000 lines changed
95+
- `size/xl`: 1000+ lines changed
96+
- Ignores lock files in calculations
97+
98+
2. **Auto Label**: Labels PRs based on changed files
99+
- Uses `.github/labeler.yml` configuration
100+
- Labels: `protocol:data`, `protocol:ui`, `protocol:system`, `ci/cd`, `documentation`, etc.
101+
102+
3. **Changeset Check**: Validates changeset presence
103+
- Warns if no changeset found
104+
- Can be bypassed with `skip-changeset` label
105+
- Ensures version tracking for releases
106+
107+
**Purpose:** Improve PR review workflow and tracking
108+
109+
---
110+
111+
### 6. Stale Issues and PRs (`.github/workflows/stale.yml`)
112+
113+
**Triggers:**
114+
- Scheduled: Daily at 01:00 UTC
115+
- Manual trigger via `workflow_dispatch`
116+
117+
**Behavior:**
118+
119+
**Issues:**
120+
- Marked stale after 60 days of inactivity
121+
- Auto-closed 14 days after marked stale
122+
- Exempt labels: `pinned`, `security`, `roadmap`
123+
124+
**Pull Requests:**
125+
- Marked stale after 30 days of inactivity
126+
- Auto-closed 7 days after marked stale
127+
- Exempt labels: `pinned`, `security`, `work-in-progress`
128+
129+
**Purpose:** Keep issue/PR lists clean and relevant
130+
131+
---
132+
133+
### 7. Validate Dependencies (`.github/workflows/validate-deps.yml`)
134+
135+
**Triggers:**
136+
- Pull requests modifying `package.json` or `pnpm-lock.yaml`
137+
- Scheduled: Weekly on Monday at 03:00 UTC
138+
- Manual trigger via `workflow_dispatch`
139+
140+
**Jobs:**
141+
142+
1. **Validate**: Dependency validation
143+
- Verifies lockfile is up-to-date
144+
- Runs security audit (high severity and above)
145+
- Lists outdated packages (scheduled runs only)
146+
147+
2. **License Check**: License compatibility verification
148+
- Checks all dependency licenses
149+
- Flags incompatible licenses (GPL, proprietary, etc.)
150+
- Allows: MIT, Apache-2.0, ISC, BSD variants, CC0, Unlicense
151+
152+
**Purpose:** Maintain dependency security and license compliance
153+
154+
---
155+
156+
### 8. Release (`.github/workflows/release.yml`)
157+
158+
**Triggers:**
159+
- Push to `main` branch
160+
161+
**Jobs:**
162+
- **Release**: Automated package publishing
163+
- Uses Changesets for version management
164+
- Creates release PRs automatically
165+
- Publishes to npm when release PR is merged
166+
- Requires `NPM_TOKEN` secret
167+
168+
**Concurrency:** Prevents concurrent release operations
169+
170+
**Purpose:** Automated semantic versioning and npm publishing
171+
172+
---
173+
174+
## Configuration Files
175+
176+
### Dependabot (`.github/dependabot.yml`)
177+
178+
**Configuration:**
179+
- **npm dependencies**: Weekly updates on Monday at 02:00 UTC
180+
- Groups minor/patch updates together
181+
- Separate groups for dev and production dependencies
182+
- Limit: 10 open PRs
183+
184+
- **GitHub Actions**: Weekly updates on Monday at 02:00 UTC
185+
- Keeps workflow actions up-to-date
186+
187+
**Commit message format:** `chore(deps):` or `chore(ci):`
188+
189+
---
190+
191+
### Auto-Labeler (`.github/labeler.yml`)
192+
193+
**Label mapping based on file paths:**
194+
195+
| Label | File Patterns |
196+
|-------|--------------|
197+
| `documentation` | `content/**`, `apps/docs/**`, `*.md` |
198+
| `protocol:data` | `packages/spec/src/data/**` |
199+
| `protocol:ui` | `packages/spec/src/ui/**` |
200+
| `protocol:system` | `packages/spec/src/system/**` |
201+
| `protocol:ai` | `packages/spec/src/ai/**` |
202+
| `ci/cd` | `.github/workflows/**`, `.github/actions/**` |
203+
| `dependencies` | `package.json`, `pnpm-lock.yaml` |
204+
| `tests` | `**/*.test.ts`, `**/*.spec.ts` |
205+
| `tooling` | `tsconfig.json`, build scripts |
206+
207+
---
208+
209+
## Required Secrets
210+
211+
The following GitHub secrets must be configured:
212+
213+
1. **`GITHUB_TOKEN`**: Automatically provided by GitHub Actions
214+
2. **`NPM_TOKEN`**: Required for npm publishing (release workflow)
215+
216+
---
217+
218+
## Permissions
219+
220+
All workflows use minimal required permissions following security best practices:
221+
222+
- Most workflows: `contents: read` only
223+
- Release workflow: `contents: write`, `pull-requests: write`
224+
- Security workflows: `security-events: write`
225+
- Documentation: `pages: write`, `id-token: write`
226+
227+
---
228+
229+
## Monitoring & Maintenance
230+
231+
### Viewing Workflow Results
232+
- Navigate to **Actions** tab in GitHub
233+
- Select specific workflow from left sidebar
234+
- View run history and logs
235+
236+
### Artifacts
237+
- Test coverage reports (30 days retention)
238+
- Build outputs (30 days retention)
239+
240+
### Security Scanning
241+
- CodeQL results: **Security** tab → **Code scanning alerts**
242+
- Dependabot alerts: **Security** tab → **Dependabot alerts**
243+
244+
---
245+
246+
## Best Practices
247+
248+
1. **Changeset Management**: Always add a changeset for user-facing changes
249+
2. **PR Size**: Keep PRs under 500 lines when possible
250+
3. **Labels**: Let automation handle labeling; add custom labels as needed
251+
4. **Security**: Address security alerts promptly
252+
5. **Dependencies**: Review and approve Dependabot PRs regularly
253+
254+
---
255+
256+
## Troubleshooting
257+
258+
### Build Failures
259+
1. Check CI workflow logs
260+
2. Verify dependencies are up-to-date
261+
3. Run `pnpm install` and `pnpm build` locally
262+
263+
### Type Check Failures
264+
1. Run `pnpm --filter @objectstack/spec exec tsc --noEmit` locally
265+
2. Fix reported type errors
266+
3. Push updated code
267+
268+
### Failed Tests
269+
1. Run `pnpm --filter @objectstack/spec test` locally
270+
2. Review failing test logs
271+
3. Fix code or update tests as needed
272+
273+
---
274+
275+
## Future Enhancements
276+
277+
Potential improvements to consider:
278+
279+
- [ ] Visual regression testing for documentation
280+
- [ ] Performance benchmarking
281+
- [ ] Automated changelog generation
282+
- [ ] Integration tests across packages
283+
- [ ] Bundle size tracking
284+
- [ ] E2E tests for documentation site
285+
286+
---
287+
288+
*Last updated: 2026-01-19*

0 commit comments

Comments
 (0)