alunduil / alunduil/zfs-replicate

Comments and documentation carry timeless why, not history, tooling that was removed, or restated code

オープン
#622 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る
enhancement
主要言語
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 はまだ評価されていません。

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。