alunduil / alunduil/zfs-replicate
Comments and doc prose carry durable why, not history or restated code
- Vorherrschende Sprache
- Python
- Sterne
- 24
- Forks
- 6
- Ø Merge
- 3 Std. 11 Min.
- Gemergte PRs (30 T.)
- 49
Beschreibung
## Summary
A sweep of every comment in `zfs/`, `zfs_test/`, `.github/`, `.devcontainer/`, and `pyproject.toml` found ten that restate the line beneath them, record migration history that blame already holds, or park feature wishes where nobody can triage them.
## Motivation
Found while auditing documentation and comments alongside #477. Most comments here already do the hard thing: `ci.yml:114` explains why squash merge makes the pull request title load-bearing, `pyproject.toml:67` explains why `target-version` stays unset, `snapshot/list.py:54` explains why `strict=False` is deliberate. None of those is recoverable from the code. The entries below are, and each one costs a reader attention on the way to the code that matters.
## Scope
History that blame already holds:
- `.devcontainer/post-create.sh:2-4` names the unmaintained devcontainer feature Vale used to come from. The script installs Vale; why it stopped using a feature is a commit message.
- `pyproject.toml:78-79` maps `PGH`, `RUF100`, and `G010` to the pre-commit hooks they replaced in 480a187. What the rules cover is durable; which hook they replaced isn't.
- `pyproject.toml:76-77` says `UP` was "deferred to keep this migration reviewable". Keep the annotation count and the #501 pointer, drop the framing that dates the comment to one commit.
Restates the code:
- `.devcontainer/post-create.sh` labels `poetry install` with `# 1) Project Python dependencies.` and `pre-commit install` with `# 2) Install the pre-commit hook into the local clone.`
- `zfs/replicate/command.py:20` ends with "kept in one place", which describes it being a module constant.
- `zfs_test/replicate_test/optional_test.py:13` says "Use try except due to lack of typing on pytest module." pytest is pinned at 9.1.1 (`pyproject.toml:59`) and has shipped `py.typed` since 6.0, so the reason no longer holds and `pytest.raises(RuntimeError)` replaces both the hand-rolled try/except and its `# noqa: E722`.
Belongs in this tracker instead:
- `zfs/replicate/cli/main.py:94` — "Improvement: exclusions from snapshots to replicate."
- `zfs/replicate/task/report.py:83` — "Check if it can be injected."
Says less than it appears to:
- `zfs/replicate/cli/click.py:12` explains a suppression with "what I assume is a metaclass construction". The suppression deserves its explanation; the next reader needs the constraint, not the guess.
Doc prose:
- `docs/adr/0001-*.md` uses ` -- ` as a connector 13 times and `docs/reference/testing.md` uses an unspaced em-dash 4 times. `Google.EmDash` is error-level but matches only the spaced form (`\s[—–]\s`), so both pass Vale today. Replacing the connectors is half the fix; the other half is deciding whether a repo rule should catch the unspaced and ASCII spellings, so this doesn't drift back.
- `docs/reference/testing.md:12-13` records that `cli_test/` and `task_test/` lack an `__init__.py`. Adding the two files deletes the sentence.
## Acceptance criteria
- [ ] No comment names a tool, hook, or feature the repository no longer uses.
- [ ] No comment restates the statement below it.
- [ ] The two parked improvements are filed as issues or dropped.
- [ ] `optional_test.py` either uses `pytest.raises` or carries a reason that holds at HEAD.
- [ ] The dash connectors are gone, and the decision on enforcing them is recorded either way.
Beitragsleitfaden
Bewertung
Dieses Issue wurde noch nicht bewertet.