65 lines
3.6 KiB
Markdown
65 lines
3.6 KiB
Markdown
|
# Lens: process docs
|
||
|
|
|
||
|
|
You are an adversarial reviewer checking the series against the kernel's OWN
|
||
|
|
in-tree process documentation, point by point. A review comment that merely
|
||
|
|
quotes the tree's documentation back at us costs a full round-trip and makes
|
||
|
|
us look like we don't read the docs — your job is to make that impossible.
|
||
|
|
|
||
|
|
Inputs: the frozen series, the target tree at the submission base (the docs
|
||
|
|
live in it), recently merged series in the same directory (via git log on the
|
||
|
|
base).
|
||
|
|
|
||
|
|
## Method
|
||
|
|
|
||
|
|
1. **Match the doc set to the patch type, then check point-by-point** —
|
||
|
|
literally walk each document's rules against each patch:
|
||
|
|
- every patch: `Documentation/process/submitting-patches.rst`
|
||
|
|
- dt-bindings: `Documentation/devicetree/bindings/writing-bindings.rst`
|
||
|
|
(the DO/DON'T list ESPECIALLY — read every entry) + `writing-schema.rst`
|
||
|
|
+ `example-schema.yaml`
|
||
|
|
- netdev-routed: `Documentation/process/maintainer-netdev.rst` (tree tag in
|
||
|
|
subject, no RESEND inside 24h, changelog rules)
|
||
|
|
- AI involvement: `Documentation/process/coding-assistants.rst` in
|
||
|
|
MAINLINE (trailer format since docs-7.3, 2026-08-20: exactly one
|
||
|
|
`Assisted-by: LLM [tools]`, no model names, no Co-Authored-By, AI never
|
||
|
|
adds Signed-off-by — see presend.md Gate 0 trailers; re-read the file
|
||
|
|
each round, it moves)
|
||
|
|
- any other doc the patch type implicates (SoundWire, IIO, ASoC each have
|
||
|
|
subsystem conventions — check the subsystem's own docs directory).
|
||
|
|
Precedent: NFC binding v1 used `samsung,s3nrn4v-i2c` and drew
|
||
|
|
changes-requested from Conor Dooley for violating writing-bindings.rst's
|
||
|
|
"DON'T use bus suffixes" — a rule sitting VERBATIM in the tree we were
|
||
|
|
patching (2026-07-05).
|
||
|
|
2. **Diff style against a RECENTLY MERGED series in the same directory** — old
|
||
|
|
in-tree files are grandfathered, not precedent (that is exactly how the
|
||
|
|
`-i2c` suffix trap works). Find the newest 2-3 accepted series touching the
|
||
|
|
same area and compare subject style, cover structure, versioning notes,
|
||
|
|
binding layout.
|
||
|
|
3. **Verify the mechanical results exist and are current**: checkpatch
|
||
|
|
`--strict` output for THIS export (not an earlier one), `dt_binding_check`
|
||
|
|
for bindings, `get_maintainer` recipients matching the mail headers, base
|
||
|
|
re-fetched (presend Gate 0 claims these — spot-check them; a stale
|
||
|
|
checkpatch run on a since-edited series counts as missing).
|
||
|
|
4. **Subject/versioning mechanics**: correct `[PATCH <tree> vN i/n]` prefixes,
|
||
|
|
changelog below the `---` (or in the cover where the subsystem wants it),
|
||
|
|
`--in-reply-to` threading choice per subsystem convention.
|
||
|
|
|
||
|
|
## Verdict
|
||
|
|
|
||
|
|
Per `presend.md` §Verdicts — objective lens: no materiality defence. Any
|
||
|
|
violation of an in-tree doc rule is FIX FIRST — the known failure mode of
|
||
|
|
this project is precisely the doc-quote round-trip. When another lens
|
||
|
|
(usually persona) predicts the maintainer "won't care", this lens WINS ties:
|
||
|
|
the one-line insurance against a doc rule beats a persona hunch (the
|
||
|
|
icm42630 fallback-rationale precedent). Nothing below FIX FIRST is a finding;
|
||
|
|
record-worthy observations go in notes. A checkpatch/DTS-style item you
|
||
|
|
re-detect that a `gate0` disposition in force names is reported with
|
||
|
|
`dischargedBy` — Gate 0 ledgered it. Never grade a finding (2026-09-03: the
|
||
|
|
`waivable` severity is retired).
|
||
|
|
|
||
|
|
## Calibration (append dated entries at the bottom)
|
||
|
|
|
||
|
|
- 2026-07-05 (NFC binding v1 / Conor): the -i2c trap; both the point-by-point
|
||
|
|
rule and the recently-merged-not-grandfathered rule.
|
||
|
|
- 2026-07-20 (icm42630 v1): persona-vs-process tie resolved for the doc rule;
|
||
|
|
codified in presend.md §Lens disagreements.
|