From c9eaae17c184a91addc2df85733db3d6339bb720 Mon Sep 17 00:00:00 2001 From: Tam Nhu Tran Date: Wed, 22 Apr 2026 15:07:12 -0400 Subject: [PATCH] docs(contrib): clarify CI lanes and parity gates --- .github/pull_request_template.md | 6 ++- CLAUDE.md | 67 ++++++++++++++------------------ CONTRIBUTING.md | 51 ++++++++++++++++++++++-- README.md | 3 ++ 4 files changed, 85 insertions(+), 42 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 3ed3a780..9002ba3f 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -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 diff --git a/CLAUDE.md b/CLAUDE.md index 11175260..ad01f074 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -41,6 +41,20 @@ gh pr checks ### 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 ` — 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.) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c283c060..a40efd91 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. diff --git a/README.md b/README.md index 4aab06f4..ea2c2617 100644 --- a/README.md +++ b/README.md @@ -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)