tiennm99/ccs
1
0
Fork 0
mirror of https://github.com/tiennm99/ccs.git synced 2026-07-15 22:21:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(contrib): clarify CI lanes and parity gates

Browse Source
This commit is contained in:
Tam Nhu Tran
2026-04-22 15:07:12 -04:00
parent b9f5783fac
commit c9eaae17c1
4 changed files with 85 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/pull_request_template.md
+4 -2
View File
@@ -6,8 +6,9 @@
Use what applies. If you skipped something, add a short note instead of forcing it.
- [ ] `bun run validate`
- [ ] `bun run validate:ci-parity`
- [ ] `bun run format && bun run validate`
- [ ] `bun run validate:ci-parity` before requesting review
- [ ] `bun run test:e2e` if this PR touches command routing, proxy flows, or workflow/release logic
- [ ] `cd ui && bun run validate` if UI changed
- [ ] Not run
@@ -20,6 +21,7 @@ Check what applies. Not every item is relevant for every PR.
- [ ] Relevant `--help` output updated if CLI behavior changed
- [ ] Tests added or updated if behavior changed
- [ ] README or local docs updated if user-facing behavior changed
- [ ] If a check failed, the PR body explains what failed and what changed to fix it
- [ ] No secrets, tokens, or private config data are included
## Docs Impact
CLAUDE.md
+30 -37
View File
@@ -41,6 +41,20 @@ gh pr checks <n>
### Absolute rule
AI MUST NOT declare a task done, close a session, or move to the next task while CI is red or still running. Leaving a PR red and moving on is the primary failure mode this protocol prevents.
### Self-Hosted Runner Awareness
- If `gh pr checks` or `gh run watch` stays queued for more than 10 minutes, assume the self-hosted runner is offline.
- Confirm on the maintainer host with `ssh docker "systemctl status actions-runner"`.
- Treat runner outages as infrastructure issues, not code failures. Do not blindly rerun local commands and hope the queue clears.
### Dev Release vs Push CI
- `CI` is the pull-request quality gate for contributor branches.
- `Push CI` is the post-merge quality signal for `dev`.
- `Dev Release` publishes the `@dev` package after `dev` changes land.
- A red `Dev Release` does **not** automatically mean contributor code failed. Check `Push CI` first.
- `dev-release.yml` currently pushes with `PAT_TOKEN` because `dev` is protected by required status checks (`typecheck`, `lint`, `format`, `build`, `test`). Do not switch it back to `github.token` unless branch protection changes with it.
## Core Function
Multi-provider profile and runtime manager for Claude Code, Factory Droid,
@@ -87,7 +101,7 @@ broader topic.
| Mistake | Consequence | Correct Action |
|---------|-------------|----------------|
| Running `validate` without `format` first | format:check fails | Run `bun run format` BEFORE validate |
| Assuming maintainability check is always strict | PR/feature branches run warning mode by default | Use `bun run maintainability:check:strict` before merge when touching debt-sensitive code |
| Treating `Dev Release` as the contributor quality signal | Publish failures on `dev` look like broken code | Check PR `CI` on the branch and `Push CI` on `dev` first |
| Using `chore:` for dev→main PR | No npm release triggered | Use `feat:` or `fix:` prefix |
| Committing directly to `main` or `dev` | Bypasses CI/review | Always use PRs |
| Manual version bump or git tag | Conflicts with semantic-release | Let CI handle versioning |
@@ -208,8 +222,8 @@ Quality gates MUST pass before pushing. **Both projects have identical workflow.
# Main project (from repo root)
bun run format # Step 1: Fix formatting
bun run lint:fix # Step 2: Fix lint issues
bun run validate # Step 3: Full gate (typecheck + lint + format + maintainability + tests)
bun run validate:ci-parity # Step 4: full CI parity gate (build + validate + base branch check)
bun run validate # Step 3: Fast gate (typecheck + lint + format + test:fast)
bun run validate:ci-parity # Step 4: PR-CI parity gate (branch check + build + full tests + e2e)
# UI project (if UI changed)
cd ui
@@ -221,17 +235,17 @@ bun run validate # Step 3: Final check (must pass)
**WHY THIS ORDER:**
- `validate` runs `format:check` which only VERIFIES—won't fix
- If format:check fails, you skipped step 1
- CI runs `validate` only (no auto-fix)—local must be clean
- `validate` now uses read-only `lint`, so autofix still belongs in step 2
- PR CI and `validate:ci-parity` both run non-mutating checks only
### What Validate Runs
### What Each Gate Runs
| Project | Command | Runs |
|---------|---------|------|
| Main | `bun run validate` | typecheck + lint:fix + format:check + test:all |
| Main | `bun run validate` | typecheck + lint + format:check + test:fast |
| Main | `bun run validate:ci-parity` | base branch check + typecheck + lint + format:check + build:all + test:all + test:e2e |
| UI | `bun run validate` | typecheck + lint:fix + format:check |
**Note:** `maintainability:check` is a SEPARATE gate — not part of `validate`. Run it explicitly via `bun run maintainability:check[:strict|:warn]` when touching debt-sensitive code or before merging to protected branches.
### ESLint Rules (ALL errors)
| Rule | Level | Notes |
@@ -255,33 +269,13 @@ bun run validate # Step 3: Final check (must pass)
### Automatic Enforcement
- `prepublishOnly` / `prepack` runs `build:all` + `validate` + `sync-version.js`
- CI/CD runs `bun run validate` on every PR (maintainability is warning mode on PR events)
- `prepack` runs `build:all`
- PR `CI` runs `typecheck`, `lint`, `format`, `build`, `test:all`, and `test:e2e`
- `Push CI` runs the same quality suite on `dev` after merge, separate from release publishing
- `Dev Release` still runs build + validate + tests before publishing and still requires `PAT_TOKEN` to push back to protected `dev`
- husky `pre-commit` runs quick lint/type/format checks
- husky `pre-push` runs the full `bun run validate:ci-parity` gate on `main`/`dev`/hotfix branches
- husky `pre-push` runs a faster feature-branch gate (`typecheck` + `lint:fix` + `format:check` + targeted checks based on changed files) before GitHub CI handles the full matrix
### Maintainability Baseline Gate
- Baseline file: `docs/metrics/maintainability-baseline.json`
- Metric collector/check script: `scripts/maintainability-baseline.js`
- Branch-aware gate wrapper: `scripts/maintainability-check.js`
- Enforcement path: `bun run maintainability:check` (run separately — NOT part of `bun run validate`; invoked by `validate:ci-parity` on protected branches)
- Gate modes:
- `strict`: protected branches (`main`, `dev`, `hotfix/*`, `kai/hotfix-*`) and equivalent CI refs
- `warn`: pull request CI and non-protected local branches (non-blocking for parallel PR workflow)
- override commands:
- `bun run maintainability:check:strict`
- `bun run maintainability:check:warn`
- Gated metrics (must not increase vs baseline):
- `processExitReferenceCount`
- `synchronousFsApiReferenceCount`
- Informational metrics (collected but not gated):
- `largeFileCountOver350Loc`
- Baseline update policy:
1. Prefer reducing the metric and keeping the baseline unchanged.
2. On protected-branch integration (strict mode), if increase is intentional and accepted, run `bun run maintainability:baseline`.
3. Commit both the code change and `docs/metrics/maintainability-baseline.json`, and state reason in PR description.
- husky `pre-push` runs a faster feature-branch gate (`typecheck` + `lint` + `format:check` + `test:fast`) plus targeted checks based on changed files
## Critical Constraints (NEVER VIOLATE)
@@ -532,17 +526,16 @@ rm -rf ~/.ccs # Clean environment
Optimized for iterative push-then-review workflow. Do NOT run the full gate on every push — CI is the safety net. Run the full gate once before asking for review / merge.
### Tier 1 — Iterative push (feature branch)
Husky `pre-push` auto-runs: `typecheck + lint:fix + format:check + build:all` plus targeted tests based on changed files. AI does **nothing extra** at push time.
Husky `pre-push` auto-runs: `typecheck + lint + format:check + test:fast` plus targeted checks based on changed files. AI does **nothing extra** at push time.
**After push (MANDATORY):** follow the [CI-First Protocol](#ci-first-protocol-mandatory) — watch CI until green. Do not move on while CI is red.
### Tier 2 — Before requesting review / merge
Run ONCE, not per push:
- [ ] `bun run validate:ci-parity` — full build + validate matches CI
- [ ] `bun run validate:ci-parity` — branch freshness + build + full non-e2e tests + e2e
- [ ] `gh pr checks <n>` — all checks green
- [ ] If touching debt-sensitive code: `bun run maintainability:check:strict`
- [ ] If strict mode fails and increase is intentional: `bun run maintainability:baseline` and commit `docs/metrics/maintainability-baseline.json`
- [ ] If UI changed: `cd ui && bun run format && bun run validate`
- [ ] If touching command routing, proxy flows, workflows, or release logic: `bun run test:e2e`
### Code / Docs / Standards (verify before merge)
- [ ] Conventional commit format (`feat:`, `fix:`, etc.)
CONTRIBUTING.md
+48 -3
View File
@@ -76,6 +76,22 @@ Rules:
- Treat `hotfix/*` as maintainer-only emergency flow from `main`.
- Delete your branch after merge.
## CI and Release Flow
CCS now uses three separate automation lanes:
- `CI` runs on pull requests to `dev` and `main`. This is the review gate for contributor branches.
- `Push CI` runs after a merge lands on `dev`. This is the code-quality signal for the shared `dev` branch.
- `Dev Release` publishes the `@dev` package after `dev` changes land. It is release automation, not the primary contributor quality signal.
If `Dev Release` is red but your PR checks were green, check `Push CI` before assuming the merged code is broken.
If `CI` or `Push CI` stays queued for more than 10 minutes, the self-hosted runner is probably offline. That is a maintainer issue, not a contributor mistake.
## AI Agent Rules
`CONTRIBUTING.md` is the human entry point. For AI agents working in this repo, the authoritative automation and workflow rules live in [CLAUDE.md](./CLAUDE.md).
## AI Review Lane
CCS PR review no longer depends on `anthropics/claude-code-action`. The repository review lane is self-hosted PR-Agent:
@@ -129,16 +145,35 @@ Use `bun run dev` from the repo root when working on the local dashboard experie
## Validation
If you can, run these before you open or update a PR:
Run this fast local gate before you open or update a PR:
```bash
bun run format
bun run lint:fix
bun run validate
```
`bun run validate` is the day-to-day contributor gate. It runs:
- `typecheck`
- `lint`
- `format:check`
- `test:fast`
Before you ask for review, or whenever you want the closest local equivalent to PR CI, run:
```bash
bun run validate:ci-parity
```
If you changed the dashboard:
`bun run validate:ci-parity` adds:
- branch freshness check against `origin/dev` or `origin/main`
- `build:all`
- full non-e2e test suite via `test:all`
- `test:e2e` with `CCS_E2E_SKIP_BUILD=1`
If you changed the dashboard, run the UI gate too:
```bash
cd ui
@@ -155,7 +190,17 @@ bun run test:native
bun run test:e2e
```
`bun run validate` is the main gate. It covers typechecking, linting, format checks, maintainability checks, and automated tests for the main project.
Use `bun run test:e2e` locally before review if you touch command routing, proxy flows, release automation, or workflow wiring and want to reproduce the same CLI e2e lane that PR CI runs.
### Why Did CI Fail?
| Symptom | Likely cause | Fix |
| --- | --- | --- |
| `format` fails in PR CI | `bun run format` was skipped locally | Run `bun run format`, recommit, push again |
| `lint` fails in PR CI | `validate` now uses read-only `lint` | Run `bun run lint:fix`, then rerun `bun run validate` |
| `test` fails in PR CI but `validate` passed | The failure is in `test:slow` or `test:e2e` | Run `bun run validate:ci-parity` locally |
| Checks stay queued for >10 min | Self-hosted runner is offline | Wait for maintainer intervention; rerunning usually does not help |
| `Dev Release` is red on `dev` after merge | Release-only failure or publish problem | Check `Push CI` first to confirm code quality |
If you cannot run the full suite, that is still fine for early or docs-only PRs. Just say what you did run, or what blocked you, in the PR.
README.md
+3
View File
@@ -177,6 +177,9 @@ ccs ollama "summarize these logs"
## Contribute And Report Safely
- Contributing guide: [CONTRIBUTING.md](./CONTRIBUTING.md)
- Daily local gate: `bun run format && bun run validate`
- Before review or merge confidence: `bun run validate:ci-parity`
- If PR checks stay queued for more than 10 minutes, assume the self-hosted runner is offline and notify a maintainer instead of retrying blindly
- Starter work:
[good first issue](https://github.com/kaitranntt/ccs/labels/good%20first%20issue),
[help wanted](https://github.com/kaitranntt/ccs/labels/help%20wanted)