Skip to content

A defect found in passing is a GitHub issue with its component label; the repository keeps no log of known defects

Decision 1031 · accepted · 2026-11-17 · issue #1010 · supersedes 940

The decision. A defect someone finds while working on something else is filed as a GitHub issue: where, what and how bad, worded neutrally, with its component label (plane, harness, tui, gui, documentation) and bug when it is wrong behaviour. One issue covers one mechanism, not whatever one chunk happened to leave behind. The repository keeps no list of known defects. This replaces the part of Decision 940 that kept docs/developer/defects.md as an index, kept the entries on pages under docs/developer/defects/ and had scripts/doc-size.exs check that they matched. The 400-line rule in Decision 940 still stands.

Why. The log had 88 open entries and 383 items. 37 of the entries were titled by the release or chunk that left them, so the only way to find a file's defects was to rg for its path. Lines went in faster than they came out, the defects were tracked twice (in the log and in the issue tracker, which is already triaged by rank), and CI had about 90 lines of checks that existed only to keep the log consistent. For #1010 every item was checked against the code. The ones still true are filed as issues, and the pull request lists them and what happened to each of the others.

Not chosen. Keeping the log and regrouping it by component: it would still be a second tracker, and its items would still miss the triage the issues get. One issue per entry: it would keep the chunk-shaped titles. A found-in-passing label: the component label already says where a defect is, and the issue's text says how it was found.

If undone. A second list grows beside the issues again, ranked by nobody. An agent would also need to read it before every change, on top of searching the issues.

Governs: AGENTS.md, docs/developer/fixing-issues.md, scripts/doc-size.exs, mkdocs.yml