alunduil / alunduil/zfs-replicate
Each testing convention sits in the Diátaxis mode its content fits
- 主要語言
- Python
- 星號
- 24
- 分支
- 6
- 平均合併
- 3 小時 11 分鐘
- 30 天內合併 PR
- 49
描述
## 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.
貢獻指南
研究方向
Start by reading docs/reference/testing.md, then check its inbound links from CONTRIBUTING.md and CLAUDE.md. Compare each section with pyproject.toml, zfs_test/conftest.py, and zfs/replicate/process.py as the issue suggests. Done means every section has an agreed destination or deletion, remaining reference material is descriptive, links are updated, and docs/reference/ is removed if empty.
由索引模型根據 Issue 內容生成。
評估
- 技術堆疊
- python
- 領域
- developer-experience, documentation, testing
- Issue 類型
- 文件
- 難度
- 5/5
- 預估耗時
- 一週以上
- 活躍度
- 活躍
- 描述清晰度
- 基本清楚
- 新手友好度
- 35/100