From ebe58a91675fb6081651eb36edaf40ffa3b12c66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20M=C3=BCller?= Date: Tue, 29 Sep 2026 21:15:01 +0000 Subject: [PATCH] :memo: Say compat is CI-only and run by hand locally MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The pipeline bullet's "(push to `main` / tag)" read like a local push hook. State plainly that `compat` has no local tier — it is not in `check`, `verify`, `test:ci` or any hook — and is run manually with `build && test:compat`. --- CONTRIBUTING.md | 9 +++++---- development/ci.md | 14 +++++++++----- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8a21e1f..7902db8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,9 +20,10 @@ the rules so agents and humans don't diverge. - **Build:** `npm run build` - **Test:** `npm run test`, `npm run test:ci` -- **Compat (CI-only):** `npm run test:compat` — type-check the suite + a consumer - fixture against the minimum supported TypeScript; needs a built `dist/` and - network access (`npx`) +- **Compat (CI-only, manual locally):** `npm run test:compat` — type-check the + suite + a consumer fixture against the minimum supported TypeScript; needs a + built `dist/` and network access (`npx`). Never part of a hook or + `check`/`verify` - **Watch:** `npm run watch` - re-runs tests on file save, humans only - **Checks:** `npm run check`, `npm run fix` - **Doc tests:** `npm run create:doc-tests` — compile the `ts`-tagged fences @@ -47,7 +48,7 @@ faster tiers catch less, slower tiers are more thorough": | `npm run fix` | manual | Auto-resolve fixable issues (lint, format) | ~3s | | `npm run maintain` | manual / CI (advisory) | `maintain:knip` + `maintain:outdated` (whole-project + network scans) | ~10s | | CI build (auto) | on push to `main` / tag | `build` job (build + correctness + coverage + packaging) — see [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml) | ~30s+ | -| CI compat (auto) | on push to `main` / tag | `compat` job — `test:compat` over the built `dist/`; gates `publish` — see [compat/](./compat) | ~15s | +| CI compat (auto) | in CI only | `compat` job — `test:compat` over the built `dist/`; never a local tier (run by hand) — see [compat/](./compat) | ~15s | | CI maintain (auto, non-blocking) | on push to `main` | `npm run maintain` — reports, never fails the build | ~10s | | CI publish (auto) | on tag | packaging checks + `publish:publint` / `publish:attw`, then the Gitea release page and `npm publish` (skipped, and the job failed, without `NPM_TOKEN`) | ~15s | diff --git a/development/ci.md b/development/ci.md index fc2a3f3..5411b79 100644 --- a/development/ci.md +++ b/development/ci.md @@ -6,9 +6,12 @@ the job graph; this file records why it is shaped the way it is. ## Pipeline - **`build`** (push to `main` / tag) — build + correctness + packaging. -- **`compat`** (push to `main` / tag) — type-check the suite and a consumer - fixture against the minimum supported TypeScript; consumes `build`'s `dist/` - and gates `publish`. See [§ TypeScript compatibility](#typescript-compatibility). +- **`compat`** (CI only) — type-check the suite and a consumer fixture against + the minimum supported TypeScript; consumes `build`'s `dist/` and gates + `publish`. It has **no local tier**: it never runs in a hook or in + `check` / `verify` / `test:ci`; run it by hand with + `npm run build && npm run test:compat`. See + [§ TypeScript compatibility](#typescript-compatibility). - **`maintain`** (push to `main`, non-blocking) — `npm run maintain`; reports, never fails the build. - **`publish`** (tag) — packaging checks + `publish:publint` / `publish:attw`, @@ -151,8 +154,9 @@ source of truth) and documented in [README § Requirements](../README.md#require put a second compiler in the local `check` / `verify` loop and every editor. - **CI-only is the point.** `npx` fetches over the network — like `maintain`'s scans, a network-bound check is never a local feedback tier (see - [workflow.md § Feedback tiers](./workflow.md#feedback-tiers)). Locally the - same gate is reproducible with `npm run build && npm run test:compat`. + [workflow.md § Feedback tiers](./workflow.md#feedback-tiers)). It is not in + `check`, `verify`, `test:ci` or any hook; locally it is run **by hand** with + `npm run build && npm run test:compat`. - **`compat` consumes `build`'s artifact** rather than rebuilding, so it judges the exact bytes `check`, `test:ci` and `publint` saw. - **`compat` gates `publish`** because the types are the feature: an artifact