From 6d281e46069db3c5af5b399deb1688255d2f1f42 Mon Sep 17 00:00:00 2001 From: iris Date: Mon, 20 Jul 2026 19:35:45 +0200 Subject: [PATCH] =?UTF-8?q?docs(#2552):=20never=20add=20#[allow(clippy::..?= =?UTF-8?q?.)]=20=E2=80=94=20fix=20lints=20instead?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit add a clippy-discipline note to docs/conventions.md under 'Building & local checks' and a short pointer bullet in CLAUDE.md so the rule is visible at first read. covers the three most common patterns that surfaced in practice (too_many_lines → extract helper, doc_markdown → backticks, must_use → handle or discard) and gives a concrete worked example (TurnAccum extraction in stats.rs). --- CLAUDE.md | 3 +++ docs/conventions.md | 14 ++++++++++++++ 2 files changed, 17 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index fae1a598..e2548902 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -165,6 +165,9 @@ The docs below own the details — this section just points at them. - **Commit style, naming, identity, reconcile verb:** → [`docs/conventions.md`](docs/conventions.md). +- **Never add `#[allow(clippy::…)]`** — fix the lint instead (extract a + helper, add backticks, etc.). Details + worked examples: → + [`docs/conventions.md`](docs/conventions.md#building--local-checks). - **NixOS / nspawn quirks** (bind mounts, conf flags, etc.): → [`docs/gotchas.md`](docs/gotchas.md). - **Turn loop, sentinels (rate-limit, auth-failed), context diff --git a/docs/conventions.md b/docs/conventions.md index c2918082..a837bfcb 100644 --- a/docs/conventions.md +++ b/docs/conventions.md @@ -472,6 +472,20 @@ nix fmt # treefmt — authoritative, NOT bare cargo fmt misses the non-rust files treefmt also covers, so always run `nix fmt` before pushing. +**Clippy discipline — never add `#[allow(clippy::…)]`.** All lints are +CI-fatal at `-D warnings` (pedantic included); every warning that fires +must be *fixed*, not silenced. Common patterns: + +- `too_many_lines` — extract a helper function or a sub-struct + (the `TurnAccum` extraction in `stats.rs` is a worked example). +- `doc_markdown` (brand name without backticks in a doc comment) — add + backticks: `` `DOMPurify` `` instead of `DOMPurify`. +- `must_use` / `unused_results` — actually handle or explicitly discard + the return value (`let _ = …` is fine when intentional). + +If a lint seems wrong for a specific call site, file an issue and ask +mara — don't add `#[allow]` speculatively. The gate is intentional. + **The devshell checks are not the full `nix flake check`.** Clippy / fmt / `cargo test` cover most gates, but `nix flake check` runs extra check derivations they don't: