alunduil / alunduil/zfs-replicate
Comments and documentation carry timeless why, not history, tooling that was removed, or restated code
- 主要言語
- Python
- スター
- 24
- フォーク
- 6
- 平均マージ
- 3時間 11分
- マージ済み PR(30日)
- 49
説明
## Summary
Remove or rewrite fifteen comments that restate the code, record why something changed, name tooling this project no longer runs, or hold notes belonging in the tracker.
## Current behaviour
`docs/adr/` is excluded throughout, since recording superseded context is what an ADR is for.
**Restates the code**
- [ ] `.devcontainer/post-create.sh:7,10` -- `# 1) Project Python dependencies.` sits above `poetry install` and `# 2) Install the pre-commit hook into the local clone.` above `pre-commit install`. Drop the numbered scaffolding; keep the `extractVersion` explanation at `:13-14`.
- [ ] `.pre-commit-config.yaml:1-2` -- the two `See https://pre-commit.com...` lines are `pre-commit sample-config` boilerplate.
- [ ] `zfs/replicate/cli/options.py:95` -- `# Excluded from mutation for the reason above ``send_group``.` restates the `# pragma: no mutate block` on the line below and sends the reader hunting for an antecedent.
- [ ] `zfs/replicate/cli/log.py:55-56` -- "The `--verbosity/-v` option, wired to the `zfs.replicate` logger" and "Read qualified as ``log.option``" describe the call directly beneath them. The load-bearing sentence, that the annotation exists because click-log is untyped, is last. Lead with it.
**Records why something changed**
- [ ] `.devcontainer/post-create.sh:2-4` -- "the linter previously provided by the unmaintained `ghcr.io/shinepukur/devcontainer-features/vale` feature".
- [ ] `pyproject.toml:101-102` -- "PGH and RUF100 stand in for the removed pygrep-hooks and yesqa hooks", and "S (above) covers python-no-eval and the bandit rule set".
**Names tooling that was removed**
- [ ] `zfs_test/replicate_test/cli_test/log_test.py:11` -- `# pylint: disable=protected-access` suppresses nothing. pylint does not run, and ruff's `SLF` rules are absent from `select` at `pyproject.toml:103`. The comment above it already explains the private access.
**Belongs in the tracker**
- [ ] `zfs/replicate/cli/main.py:94` -- `# Improvement: exclusions from snapshots to replicate.` is a feature idea; file it or drop it.
- [ ] `zfs/replicate/task/report.py:82` -- `# Excising this makes typing happy. Check if it can be injected.` is an open question, and `this` has no antecedent a stranger can resolve.
**Prose register**
- [ ] `zfs_test/conftest.py:14,15` -- `---` stands in for an em-dash twice, in `one process---stats` and `mutant---and`. Split the sentence or use a colon.
**Weaker, worth a judgment call**
- [ ] `zfs/replicate/command.py:20` -- ", kept in one place" justifies the constant existing, which naming already does. Keep the first half; `("/usr/bin/env", "-")` is not self-evident.
- [ ] `zfs/replicate/cli/options.py:68-69,140-141` -- "so the argument count is inherent to collapsing them into one kwarg" defends a count nothing flags. `options.py` carries no suppression.
- [ ] `zfs/replicate/cli/click.py:12-13` -- "what I assume is a metaclass construction" hedges where it should state the constraint.
- [ ] `.github/workflows/ci.yml:43-47,104-108` -- ten `# EOL YYYY-MM` markers, duplicated across both matrices. #616 already covers the duplication.
## Motivation
Found while auditing the tree after #617, re-checked against HEAD while working #505.
`CLAUDE.md` sets the test for a comment: would this be true and useful in eighteen months to a stranger? Each item above fails it in one of five ways.
One finding is worth more than tidiness. `log_test.py:11` invokes pylint, which this project does not run, so it is a suppression that suppresses nothing.
## Scope
.devcontainer/post-create.sh, .pre-commit-config.yaml, pyproject.toml, .github/workflows/ci.yml, zfs/replicate/cli/main.py, zfs/replicate/cli/log.py, zfs/replicate/cli/options.py, zfs/replicate/cli/click.py, zfs/replicate/command.py, zfs/replicate/task/report.py, zfs_test/conftest.py, zfs_test/replicate_test/cli_test/log_test.py
## Out of scope
- `docs/adr/`. Recording superseded context is what an ADR is for, including its `--` dashes.
- The `ci.yml` EOL markers as a duplication problem. #616 carries that; this issue only questions whether dated markers belong in a comment at all.
## Acceptance criteria
- [ ] No comment outside `docs/adr/` explains why something changed
- [ ] No comment names pylint, black, isort, flake8, pydocstyle, bandit, pygrep-hooks, or yesqa
- [ ] Every remaining suppression suppresses a rule that is actually selected
- [ ] No comment substitutes `--` or `---` for punctuation
- [ ] Behaviour is unchanged and the suite passes untouched
## Related issues
#621 covers the twentieth finding from the original audit, `docs/reference/testing.md:11-12`, which documented two test directories as exceptions to the `__init__.py` convention instead of closing the gap.
#620 covers `task/report.py`'s `_action`, whose comment is the finding above. Whichever lands second takes the conflict.
## Notes
Seven findings from the first revision of this issue are fixed at HEAD and struck from the scope above.
#661 (`3367287`) removed all four `CLAUDE.md` findings: the `This file gives Claude Code...` hot start, the `/insights` origin story, the list of five removed tools, and the `## Why this project specifically` section. It also cleared the four em-dashes in `docs/reference/testing.md`, which now holds only `--doctest-modules` and `--cov` as flags.
#695 (`751a992`) enabled `UP`, so the "deferred to keep this migration reviewable" note in `pyproject.toml` is gone.
`snapshot/send.py`'s "the parameter count crosses pylint's threshold" comment is gone; only the `# noqa: PLR0913` remains, now at `:35` and `:63`.
The `CLAUDE.md` correctness question the first revision raised, that scope discipline "avoids prematurely shipping something blocked by an earlier milestone" while release-please derives versions from commit types, no longer applies. The current `CLAUDE.md` states the opposite: milestones don't gate work.
コントリビューションガイド
評価
この issue はまだ評価されていません。