alunduil / alunduil/zfs-replicate
Each testing convention sits in the Diátaxis mode its content fits
- Lingua principale
- Python
- Stelle
- 24
- Fork
- 6
- Merge medio
- 3h 11m
- PR unite (30g)
- 49
Descrizione
## User story
As a **contributor writing a test**, I want **each convention where its kind of content and its reader put it**, so that **I find it by looking rather than by following a pointer, and one file stops absorbing whatever has nowhere else to go**.
## Current workaround
Every testing convention lives in `docs/reference/testing.md`. Two things sit awkwardly there.
Diátaxis reference describes, and only describes. Seven of that file's eight sections prescribe instead: Layout says where a test class goes and what its docstring holds, Fixtures says when to inject a collaborator rather than write a value, Property tests says when to reach for `@given`, Regression tests says what a bug fix adds. Rules addressed to someone performing a task are not reference material. Strip the prescription and little survives, and most of what does restates something else: the pytest invocation and the `S101` ignore restate `pyproject.toml`, and `process.py` being the only place the project spawns a process restates that module's own docstring.
The audience is the odd one out too. The rest of `docs/` addresses people running zfs-replicate, both how-to guides included. This file addresses people changing it, and its only inbound links are `CONTRIBUTING.md` and `CLAUDE.md`. It is also the only file under `docs/reference/`, so if it moves, the directory goes with it.
The file grows, which is what a catch-all looks like: #481 created it, #675 added the class and fixture rules, #674 added mutation testing.
## Alternatives considered
- Rehome the rules to `CONTRIBUTING.md`, which already links here and already addresses contributors.
- Enforce what a linter can enforce, and delete the prose that restates it.
- Move each rule to the file it governs: the fixture convention onto `zfs_test/conftest.py`, the process-boundary rule onto `zfs/replicate/process.py`.
- Recast as `docs/explanation/`, non-normative, saying why the suite is shaped this way rather than what to do.
- Recast as a how-to, task-shaped, along the lines of "How to add a test".
- Keep it as reference, stripped to description alone, accepting that little remains.
Doing nothing is also a defensible outcome, if the mismatch costs less than moving everything.
## Acceptance criteria draft
- [ ] Every section gets its own verdict rather than the file getting one: reference, how-to, explanation, `CONTRIBUTING.md`, tooling, the code it governs, or deletion.
- [ ] Whatever stays under `docs/reference/` describes rather than prescribes, and doesn't restate `pyproject.toml` or a module docstring.
- [ ] Anything a linter could check is filed for enforcement instead of being restated in prose.
- [ ] `CONTRIBUTING.md` and `CLAUDE.md` point wherever the conventions land.
- [ ] `docs/reference/` is removed if nothing stays in it.
## Additional context
- [Diátaxis on reference](https://diataxis.fr/reference/): "Reference material is austere: it describes, and only describes."
- The repo's `docs/` layout implies Diátaxis by its directory names, but nothing states the adoption. Settling that may belong to this issue or to an ADR.
Guida per i contributori
Apri la guida per i contributori
Valutazione
Questa issue non è ancora stata valutata.