From 2cd3932c8deb5b214d28b6d4ffc90592a8b711d6 Mon Sep 17 00:00:00 2001 From: Serkyo Date: Tue, 7 Jul 2026 01:28:57 +0200 Subject: [PATCH] docs(workspace): document lint-suppression policy --- AGENTS.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 5a2ba06..49993cf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -107,6 +107,15 @@ Subsystems that are I/O- or hardware-bound — the `renderer`/Vulkan GPU paths, Unit tests live beside the code (`#[cfg(test)] mod tests`) and run with `cargo test -p `. +## Lint suppressions + +The workspace opts into strict linting: Clippy's `pedantic` group plus restriction lints that ban `unwrap`, `expect`, and `print` outside the permitted contexts (see `[workspace.lints]` in the root `Cargo.toml`). Suppressions are therefore expected at specific sites, and are governed by these rules: + +- **Prefer `#[expect(...)]` over `#[allow(...)]`** for a localised suppression. An `#[expect]` becomes a warning (`unfulfilled_lint_expectations`) if the lint it names no longer fires, so an obsolete suppression surfaces and is removed instead of lingering silently. `#[allow]` never self-reports and accumulates into dead noise. +- **Suppress narrowly.** Name the exact lint(s), and attach the attribute to the smallest scope that covers the site — a statement, expression, or item — never a broad crate-level `#![allow]`. The sole standing exception is a deliberate crate-wide policy, such as `#![allow(unsafe_code)]` in `renderer`, where the suppression is the architectural intent rather than a local waiver. +- **Justify non-obvious suppressions.** Where the reason a lint is safe to suppress is not self-evident from the surrounding code, precede the attribute with a brief comment stating why (for example, that a cast is provably in range). +- **Never suppress `correctness`-tier lints.** Those indicate real defects; fix the code instead. + ## Documentation style - **Objective Tone:** All comments (both doc comments `///` and inline `//`) must be written in a formal, objective, and neutral tone.