alunduil / alunduil/zfs-replicate

Comments and doc prose carry durable why, not history or restated code

Offen
#666 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
enhancement
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

Beitragsleitfaden öffnen

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.