Marc Billow
7086b134c0
CONTRIBUTING.md gains a "Code comments" section: comment the why not the what, keep it to a sentence or two with a pointer to the load-bearing evidence, don't re-derive a sibling's already-documented reasoning, and move failed-attempt investigation logs out of inline comments. Applied that policy across the codebase: condensed sprawling module docstrings, per-entity essays, and multi-paragraph rationale blocks down to their load-bearing conclusions, while preserving the actual "why" (issue numbers, calibration evidence, gotchas, don't-guess rationale). No functional code changed — verified via diff review, ruff, ty, and the full pytest suite (1211 passed). One inline investigation log (the AC filter-reset "tried and failed" notes) moved to docs/investigations/ac-filter-reset.md rather than being deleted, per the new guideline on where that kind of record belongs.
59 lines
3.0 KiB
Markdown
59 lines
3.0 KiB
Markdown
# Contributing
|
|
|
|
See the README's [Contributing](README.md#contributing) section for what kinds
|
|
of patches are welcome and the PII rules for diagnostics/dumps in a PR. This
|
|
file covers how changes get committed.
|
|
|
|
## Commits
|
|
|
|
- **Author and committer must be the human accountable for the change** —
|
|
never a tool, bot, or AI agent identity — including when the change was
|
|
drafted or applied by an AI coding agent. Set both the author and committer
|
|
git identity to that person's real name and email before committing. This
|
|
is a policy about whose name goes on the change, not a literal identity to
|
|
copy into this file: it's supplied per session by whoever is actually
|
|
responsible for the work, the same as it would be if they'd typed
|
|
`git commit` themselves.
|
|
- **No co-author trailers for AI tools or assistants.** Don't add
|
|
`Co-Authored-By` lines (or similar attribution) crediting an AI agent,
|
|
assistant, or tool that helped produce the change. The commit is
|
|
attributed entirely to the accountable human.
|
|
|
|
## Code comments
|
|
|
|
This codebase reverse-engineers undocumented device APIs, so comments
|
|
recording *why* a decision was made (a calibration, a rejected write, an
|
|
issue number a quirk was confirmed against) are genuinely valuable — more
|
|
valuable than in most codebases. That's exactly why comments here need
|
|
discipline: it's easy for "explain the reasoning" to slide into "narrate
|
|
the whole investigation," and a file where every line has a paragraph
|
|
under it is as hard to read as one with no comments at all. Keep the
|
|
conclusion; cut the journey.
|
|
|
|
- **Comment the "why," never the "what."** If a comment just restates what
|
|
the next line already says, delete it. Code should read clearly enough
|
|
on its own that comments are only needed for the non-obvious.
|
|
- **One or two sentences, not an essay.** State the conclusion and the one
|
|
piece of evidence that makes it credible (an issue number, a model name,
|
|
a single confirming observation). Don't reproduce the full
|
|
investigation — every dump checked, every attempt that failed, every
|
|
hypothesis considered and discarded. A future reader needs to trust the
|
|
conclusion and know where to look if they need to redo the work, not
|
|
relive it.
|
|
- **A pointer, not a re-derivation.** Cite the issue/model once; don't
|
|
re-explain a sibling function's already-documented reasoning. Reference
|
|
it (`same reasoning as X above`) instead of restating it.
|
|
- **Module/class docstrings are a short orientation, not a design doc.**
|
|
A few lines on purpose and any cross-cutting invariant is enough.
|
|
- **Failed-attempt logs don't belong inline.** If an investigation into an
|
|
unsolved problem produced real negative results worth preserving (e.g. a
|
|
reset mechanism nobody could find), put them in an issue or docs, not a
|
|
block comment several times longer than the code it sits above.
|
|
- **When in doubt, cut.** If deleting a comment wouldn't lose real
|
|
understanding, it's noise. Prefer trimming an existing comment over
|
|
adding a new one.
|
|
|
|
## For AI coding agents
|
|
|
|
See `AGENTS.md`.
|