alunduil / alunduil/zfs-replicate

Each testing convention sits in the Diátaxis mode its content fits

未關閉
#677 0 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視
enhancement
主要語言
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

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。