alunduil / alunduil/zfs-replicate

No documentation page holds a second copy of a test module

Aperta
#681 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
enhancement
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.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.