From eee73a151d98fb2fad35f0273db05cea6ed41fe8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20M=C3=BCller?= Date: Fri, 11 Sep 2026 20:23:36 +0000 Subject: [PATCH] :memo: Point feedback tiers at ci.yml as the source of truth The CI build row and the publishing workflow restated a step list that had already drifted from the workflow (build + publint in build, publish consuming the build artifact). Reference .gitea/workflows/ci.yml instead of duplicating the job graph. --- CONTRIBUTING.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e36b231..bd34ce7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,18 +44,18 @@ Separately, some top-level scripts are **bare** (no prefix): the entry points th The tools are organized into a feedback ladder. Each tier catches different things at different costs; the rule of thumb is "earlier tiers fire more often, faster tiers catch less, slower tiers are more thorough": -| Tier | When | What it runs | Time | -| -------------------------------- | ---------------------- | --------------------------------------------------------------------- | ----- | -| `npm run watch` | manual | `watch:test` — re-runs tests on file save | ~0.1s | -| Pre-commit (auto) | on stage | tsc + oxlint + oxfmt + cspell (staged files only) | ~1.3s | -| Pre-push (auto) | on push | `npm test` (full tsc + unit tests) | ~3.5s | -| `npm run check` | manual | Correctness gates: tsc + oxlint + oxfmt + cspell (whole project) | ~3s | -| `npm run verify` | manual | Definition of done: `npm run check` + unit tests, one shot | ~6s | -| `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` | `npm run check` + `npm run test:ci` | ~30s+ | -| CI maintain (auto, non-blocking) | on push to `main` | `npm run maintain` — reports, never fails the build | ~10s | -| CI publish (auto) | on tag | `publish:publint` + `publish:attw`, then `npm publish` | ~10s | +| Tier | When | What it runs | Time | +| -------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------- | ----- | +| `npm run watch` | manual | `watch:test` — re-runs tests on file save | ~0.1s | +| Pre-commit (auto) | on stage | tsc + oxlint + oxfmt + cspell (staged files only) | ~1.3s | +| Pre-push (auto) | on push | `npm test` (full tsc + unit tests) | ~3.5s | +| `npm run check` | manual | Correctness gates: tsc + oxlint + oxfmt + cspell (whole project) | ~3s | +| `npm run verify` | manual | Definition of done: `npm run check` + unit tests, one shot | ~6s | +| `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` | `build` job (build + correctness + packaging) — see [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml) | ~30s+ | +| CI maintain (auto, non-blocking) | on push to `main` | `npm run maintain` — reports, never fails the build | ~10s | +| CI publish (auto) | on tag | `publish:publint` + `publish:attw`, then `npm publish` | ~10s | ### Why these splits? @@ -96,4 +96,4 @@ Publishing is CI-only by policy. Local `npm publish` is not supported. The maint 1. All intended changes are merged to `main` and passing CI. 2. The maintainer runs `npm run create:release` — an interactive prompt suggests a version (based on the latest CHANGELOG entry); the maintainer confirms or edits it. 3. `scripts/release.sh` creates a single release commit (changelog + package.json bump, amended into one commit), tags it, and pushes everything to Gitea. -4. CI runs on the push: `npm run check` + `npm run test:ci` on the commit; then the `publish` job fires on the tag: `build` → `publish:publint` → `publish:attw` → `npm publish --access public`. The publish-tier checks must pass before the artifact is published. +4. CI runs on the push (the `build` and `maintain` jobs); the `publish` job then fires on the tag, consuming the `dist/` artifact the `build` job produced. The job graph lives in [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml) — keep that file, not this list, as the source of truth. The publish-tier checks must pass before the artifact is published.