alunduil / alunduil/zfs-replicate
Vale covers every prose surface: docs, AI instructions, docstrings, and comments
- Lingua principale
- Python
- Stelle
- 24
- Fork
- 6
- Merge medio
- 3h 11m
- PR unite (30g)
- 49
Descrizione
## Summary
Vale's coverage extends past markdown to the prose inside the Python source — docstrings and comments — so one configuration holds every surface where this project writes prose.
## Motivation
Vale reads the repo's markdown today, and #664 consolidates the six upstream packs into one project style. Neither reaches the prose inside `zfs/` and `zfs_test/`. Docstrings are checked for *form* by pep257 through ruff (#698) and for nothing else. Comments are audited by hand when someone reads them — #666 found ten defects that way, which works once and then decays.
This repo is the right proving ground. alunduil-chezmoi#660 records four incompatible fleet answers to which Vale rules apply to AI-targeted docs, and this repo holds the strictest of them: all nineteen rules stay active on `CLAUDE.md`, with the acceptance criterion of rewriting the file until the human pack passes. A repo arguing the human bar is the right bar is where extending that bar to the remaining surfaces gets tested honestly. Settling all four here gives the other three repos a measured decision to converge on rather than a fifth local answer.
## Scope
- Establish what Vale reads today rather than assuming it. `[*]` in `.vale.ini` is not evidence that the Python sources are linted, and the pre-commit hook's own file scoping decides as much as the config does.
- Map Vale's comment and docstring scopes onto `*.py`, and decide which of the project style's rules apply to each. A docstring is reference prose; an inline comment is a terse note. The sentence-length and passive rules that suit `docs/` will not suit both.
- Decide the level each rule ships at per surface. Warnings exit 0, so a rule below `error` records an intention rather than enforcing one.
- Bring the existing docstrings and comments into line, or record the exemption where the register genuinely differs.
- Write the four surfaces and their rule sets down in one place, so the next repo lifts a decision instead of re-deriving it.
## Acceptance criteria
- [ ] The current Vale coverage of `*.py` is established and recorded, not assumed
- [ ] `.vale.ini` scopes rules to docstrings and to comments explicitly
- [ ] Each of the four surfaces — human docs, AI instructions, docstrings, comments — has a stated rule set and level
- [ ] Vale passes over the whole repo at the chosen levels, verified by asserting rules fire rather than by a clean run
- [ ] The per-surface decision is recorded somewhere another repo can lift it from
## Additional context
- #664 is the prerequisite — extend one project style, not six overlapping packs. Carried as a blocked-by edge.
- #476 and PR #512 add a scoped sentence-length rule for AI instruction files; #664 notes it belongs in the project style rather than a second local one.
- #666 audits comments by hand and finds ten defects. This turns that into a standing check. Its last criterion — whether a repo rule should catch the unspaced and ASCII dash spellings — is the same question at a smaller scale.
- #698 recorded why docstrings stay on pep257. That governs form; this governs the prose inside them.
- alunduil-chezmoi#660 is the fleet decision this feeds.
- Gates alunduil/blog.alunduil.com#342, a post whose argument needs the practice finished before it claims the practice paid off.
Verification here has to assert that rules fire: Vale fails open on a style directory it cannot resolve, reporting zero rules and no error while `vale ls-config` still lists the style.
Guida per i contributori
Apri la guida per i contributori
Valutazione
Questa issue non è ancora stata valutata.