alunduil / alunduil/zfs-replicate
No documentation page holds a second copy of a test module
- Lingua principale
- Python
- Stelle
- 24
- Fork
- 6
- Merge medio
- 3h 11m
- PR unite (30g)
- 49
Descrizione
## User story
As a **contributor changing a test**, I want **documentation to point at real modules rather than quote them**, so that **changing a test cannot leave a page describing code that no longer exists**.
## Current workaround
`docs/reference/testing.md` carries two fenced Python blocks, each a copy of a real test module: a `@given` round-trip lifted from `snapshot_test/list_test.py`, and a `CliRunner` invocation lifted from `cli_test/main_test.py`. Neither is generated or checked. Keeping them current is a thing a contributor has to remember.
It has already slipped twice. The `@given` block carried a `# type: ignore[misc]` that the real test had dropped. The class docstring in that same block contradicted the rule stated sixty lines above it, until #675 caught it during an audit of that very file.
A pointer does the job without the copy: name the module, and a reader who wants the example opens code that is current by construction.
## Alternatives considered
- Replace each block with a sentence naming the module to read.
- Keep the blocks and add a check that they match their source, which is machinery for two examples.
- Keep them and accept the drift, on the grounds that an inline example is worth more to a newcomer than a path is.
## Acceptance criteria draft
- [ ] No page under `docs/` quotes a test module it does not generate or check.
- [ ] Whatever replaces a block leads a reader to the module by name.
## Additional context
Blocked by #677: that issue may move, recast, or delete `docs/reference/testing.md`, and the answer decides whether these blocks need replacing or simply go with the file. The rule outlives the file either way, which is why this is separate.
Guida per i contributori
Apri la guida per i contributori
Valutazione
Questa issue non è ancora stata valutata.