From 286574cf39f3fc7fc78e1c2445accef911b05427 Mon Sep 17 00:00:00 2001 From: Diego Rodrigues de Sa e Souza Date: Fri, 24 Jul 2026 10:00:19 -0300 Subject: [PATCH] docs: one golden path across PR template, CONTRIBUTING, GEMINI, AGENTS + CI milestones in ROADMAP (#8380) Contributor guidance contradicted itself in four places (found in the #8084 review): - pull_request_template.md + CONTRIBUTING.md asked contributors to run the FULL unit suite + coverage gate locally, while the maintainer's stated golden path (#8273/#8329) is: focused tests for the change locally; full suite, coverage, and build are CI's job. On 16GB hosts the full local chain has saturated machines (#8084 incident report). - GEMINI.md demanded coverage >= 75/75/75/70 while the official CI gate is 60/60/60/60 (quality-baseline ratchet on top). - AGENTS.md fork workflow said to branch from upstream/main; the default branch is the active release/vX.Y.Z line (main only receives release squash-merges). Also makes the #8084 CI direction explicit in the public ROADMAP: lane consolidation (3.8.51), one CI policy for release/** and main (3.8.52), full-regression authority -> merge queue after TIA shadow evidence (3.8.54), preview-artifact + build-once rehearsal inside the 3.8.58 dry-run. Refs #8329 Refs #8084 --- .github/pull_request_template.md | 8 +++++--- AGENTS.md | 10 +++++++--- CONTRIBUTING.md | 11 +++++++---- GEMINI.md | 2 +- docs/ROADMAP.md | 8 ++++---- 5 files changed, 24 insertions(+), 15 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index b69e9ff215..555efff047 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -9,10 +9,12 @@ ## Validation +Run only the focused loop for what you changed — the full unit suite, Vitest, the +60% coverage gate, and the production build all run in CI on this PR (#8329): + +- [ ] Focused tests for the change: `node --import tsx/esm --test tests/unit/.test.ts` - [ ] `npm run lint` -- [ ] `npm run test:unit` -- [ ] `npm run test:coverage` -- [ ] Coverage is still `>= 60%` for statements, lines, functions, and branches +- [ ] Production-code changes include a new or updated automated test in this PR - [ ] SonarQube PR analysis is green or any remaining issues are explicitly documented below ## Tests Added Or Updated diff --git a/AGENTS.md b/AGENTS.md index e34d1cd33e..cc76b1d408 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -570,12 +570,16 @@ This repository is a fork of `diegosouzapw/OmniRoute`. Keep fork-only operationa changes (for example GHCR image publishing, personal deployment workflows, or local automation) out of upstream contribution PRs. -When preparing a PR for upstream, always start the work branch from `upstream/main`, -not from this fork's `main`: +When preparing a PR for upstream, always start the work branch from the upstream +**default branch** — the active `release/vX.Y.Z` line (today `release/v3.8.49`). +Never branch from `main`: `main` only receives release squash-merges, so a branch +cut there is weeks behind and produces conflict-heavy PRs +(see `CONTRIBUTING.md` and `docs/ops/BRANCHING_MODEL.md`): ```bash git fetch upstream -git switch -c upstream/main +# the default branch is the active release line, e.g. release/v3.8.49 +git switch -c upstream/release/vX.Y.Z ``` Only cherry-pick or reapply the changes intended for the upstream PR. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d5395a97cc..36b219e832 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -198,11 +198,14 @@ Coverage notes: ### Pull Request Requirements -Before opening or merging a PR: +Before opening a PR, run the focused loop for what you changed. The full unit suite +(4 CI shards), Vitest, the **60%+** coverage gate, and the production build are CI's +responsibility — running them locally adds no signal the PR checks will not already +give you, and on smaller machines it can saturate the host (#8084): -- Run `npm run test:unit` -- Run `npm run test:coverage` -- Ensure the coverage gate stays at **60%+** statements/lines/functions/branches +- Run the test files that cover your change: `node --import tsx/esm --test tests/unit/.test.ts` +- Run `npm run lint` +- Include or update automated tests in the same PR whenever production code changes - Include the changed or added test files in the PR description when production code changed - Check the SonarQube result on the PR when the project secrets are configured in CI diff --git a/GEMINI.md b/GEMINI.md index 64525f17e2..31cc71e761 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -27,7 +27,7 @@ When creating _any_ validation tests or one-off logic scripts, default to using 7. **Never bypass Husky hooks** (`--no-verify`, `--no-gpg-sign`) without explicit operator approval. 8. **Always validate inputs with Zod schemas** from `src/shared/validation/schemas.ts`. 9. **Always include tests when changing production code** (`src/`, `open-sse/`, `electron/`, `bin/`). -10. **Coverage must stay** ≥ 75 % statements / 75 % lines / 75 % functions / 70 % branches (real measured: ~82 %). +10. **Coverage must stay** ≥ 60 % statements / lines / functions / branches — the official CI gate (`npm run test:coverage`). The ratchet baseline in `quality-baseline.json` may freeze a higher floor; never regress it. ## 3. Codebase navigation diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 1f7c21e7ee..e3a2251c59 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -26,10 +26,10 @@ mandatory quality-gate battery before new merges open. | Version | Focus | | --- | --- | | 3.8.50 | CI safety net on release branches · dead-code cleanup · community-reported catalog/topology bug fixes · contributor "golden path" guide | -| 3.8.51 | Executor registry (in-place) · end-to-end provider-journey contract test becomes a CI gate · official scoped-test dev loop | -| 3.8.52 | `combo.ts` decomposition · routing-strategy registry · unified model-catalog contract for `/v1/models` | +| 3.8.51 | Executor registry (in-place) · end-to-end provider-journey contract test becomes a CI gate · official scoped-test dev loop · CI lane consolidation (shared install/setup across gate jobs, #8084) | +| 3.8.52 | `combo.ts` decomposition · routing-strategy registry · unified model-catalog contract for `/v1/models` · one CI policy for PRs to `release/**` and `main` (#8084) | | 3.8.53 | `chatCore.ts` decomposition · headless mode (`OMNIROUTE_HEADLESS=1`) · local candidate build/promote loop | -| 3.8.54 | Release infrastructure (dormant): channels, labels, PR templates, merge queue · public feature-freeze announcement | +| 3.8.54 | Release infrastructure (dormant): channels, labels, PR templates, merge queue · full-regression authority moves to the merge queue once TIA shadow evidence clears (#8084) · public feature-freeze announcement | ## Phase 2 — Validation (3.8.55 → 3.8.59) @@ -41,7 +41,7 @@ the v4 channel when it opens). Fixes, docs, i18n, and provider updates keep flow | 3.8.55 | Characterization tests for every extraction candidate · coupling re-measurement | | 3.8.56 | Extended canary · performance baselines (heap, TTFB, build) | | 3.8.57 | Security & compliance sweep · publish provenance (OIDC) rehearsal | -| 3.8.58 | Full dry-run of the 3.9.0 cut (branches, channels, forward-port) | +| 3.8.58 | Full dry-run of the 3.9.0 cut (branches, channels, forward-port) — includes the PR preview-artifact + build-once promotion rehearsal (#8084) | | 3.8.59 | Final freeze · full-suite audit · GO/NO-GO | ## Phase 3 — v3.9.0 LTS