Prose in one file pins code in another, and nothing brings the change back to it
- Lingua principale
- Rust
- Stelle
- 9
- Fork
- 1
- Merge medio
- 11h 46m
- PR unite (30g)
- 62
Descrizione
## Summary
Prose in one file describes code in another, and nothing brings the person
changing that code back to it. #362 adds an obligation covering a file's own
documentation and deliberately stops there, because the search that finds the
cross-file case is one I could not state correctly — two attempts in that PR
were both wrong.
## Where it already bites
`docs/testing.md` is the largest instance in the tree. Its tracing sections name
`src/runtime/load.rs`, `src/runtime/channel.rs`, `src/kernel/producer.rs`,
`src/kernel/conformance/quit.rs` and `tests/observability.rs`, and pin exact
values from them — an emission sequence of `[3, 2, 1, 0]`, a positional read of
`ids[0]` against `ids[2]`. None of those files points back.
The same document says so about itself: its note that `u64_values(...).last()`
does not compile is followed by "An edit that added `last()` to `Readings` would
pass the whole run. … review is what holds them."
## What is known
`docs/rfcs/pre-review-checklist.md` has worked part of this out for RFC review,
and its entries record what does *not* find a stale restatement: a stale one
rarely shares vocabulary with the sentence that made it stale, so a search for
the changed sentence, or for a renamed identifier, goes straight past it. What
found them in PR #240 and PR #246 was the claim's subject vocabulary and the
concept removed.
That method is written for someone revising a contract document, not for someone
changing a runtime and unaware that any prose depends on it.
## What would close this
Something the person changing the code can act on without already knowing which
documents describe it. Options worth weighing rather than a decided design:
- a check that fails when prose names an item that no longer exists — the tree
has no link checker for Markdown, and 563 intra-doc links in `src/` show the
same idea works where rustdoc can see it
- a convention that prose naming an item from another file names it in a form
something resolves
- accepting review as the mechanism, and saying so in the document rather than
leaving it implied
## Acceptance criteria
- [ ] A contributor changing code in `src/` can find out whether prose elsewhere
depends on it, without knowing in advance that it does.
- [ ] Whatever is chosen is recorded where a contributor will meet it, not only
in a pull request.
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Start with docs/rfcs/pre-review-checklist.md and inspect the cross-file examples in docs/testing.md, including the referenced src/ and tests/ files. Review PRs #240, #246, and #362 for prior constraints and approaches. Done means a contributor changing src/ can discover dependent prose without prior knowledge, and the chosen practice is recorded where contributors will encounter it.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- rust
- Ambito
- developer-experience, documentation
- Tipo di issue
- Funzionalità
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Stato di attività
- Attiva
- Chiarezza
- Da chiarire
- Idoneità per principianti
- 30/100