docs: describe the generator in the present tense - #46
Merged
Conversation
The docstring enumerates what a mirror templates and comes up one short: `_TEMPLATED['rs']` has five entries, and the `-rs` gitignore is the one missing. That matters more than a count usually would, because the paragraph frames the templated and verbatim split as the whole design, so a reader auditing which files are authored per mirror finds four and stops. Both this docstring and CLAUDE.md then spent three sentences on a kind of file that no longer exists, in the shape a reader who never saw it gains nothing from: there used to be a third, that copy is gone, retiring it removed a duplicate. The argument inside is worth keeping and does not need the history -- each mirror authors its own manifest, and that is not a duplicate because the two id sets are disjoint and this repository serves neither. Stated that way it answers the question a reader actually has, which is why the manifests are not derived from one file. Two smaller cuts of the same kind in CLAUDE.md: a `now` that dated a sentence about the mirror-diff window, and a clause naming the last file to have carried a DEVIATION comment, which the sentence before it already covers by saying none does. The generator's output is byte-identical before and after, checked by building both mirrors and diffing the trees. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Code Review by Qodo🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)
Great, no issues found!Qodo reviewed your code and found no material issues that require reviewTip of the day💡 Did you know, you can add REVIEW.md to your repo root and Qodo follows it on every PR |
PR Summary by QodoDocument mirror generation in present tense
AI Description
Diagram
High-Level Assessment
Files changed (2)
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #46 +/- ##
=======================================
Coverage 87.40% 87.40%
=======================================
Files 3 3
Lines 691 691
=======================================
Hits 604 604
Misses 87 87 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
The templated-file list conflicted: this branch added the `-rs` gitignore to it and main added the security policy, in the same sentence. Both belong, so the resolution names both. The `TEMPLATES` entries main added for `SECURITY.md` are untouched, and the generator still writes it into each mirror.
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
The changes are documentation-only and accurately reflect the current generator/templates without affecting any code paths.
Pull request overview
Updates repository documentation to describe the mirror generator’s design in accurate present-tense terms, aligning scripts/generate_mirrors.py’s docstring and CLAUDE.md with the current mirror layout (including the -rs .gitignore) without changing generator behavior.
Changes:
- Corrects and tightens
scripts/generate_mirrors.py’s docstring to list all templated files (including the-rsgitignore) and remove historical narration. - Updates
CLAUDE.md’s mirror-generation section to describe the hook-manifest authoring rationale without references to removed legacy structure.
File summaries
| File | Description |
|---|---|
| scripts/generate_mirrors.py | Docstring now accurately enumerates templated vs. verbatim mirror files, including the -rs .gitignore, in present tense. |
| CLAUDE.md | Removes outdated historical phrasing; keeps the rationale for per-mirror hook manifests and the mirror-diff window in present tense. |
Review details
- Files reviewed: 2/2 changed files
- Comments generated: 0
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changes, and why
The templated-file list is one short.
scripts/generate_mirrors.py's docstring names "the hook manifest, the build manifest, the readme and the contributing note"._TEMPLATED['rs']has five entries —gitignore→.gitignoretoo, explained by an inline comment thirty lines down but absent from the list. The paragraph frames the templated/verbatim split as "the whole design", so a reader auditing which files are authored per mirror finds four and stops. The live-rsmirror carries that.gitignore.Both this docstring and
CLAUDE.mdspent three sentences on a kind of file that no longer exists — "there used to be a third", "that copy is gone", "retiring it removed the last duplicate rather than creating one". A reader who never saw the removed copy gains nothing from the narration, and the paragraph reads as though a third mirror kind might still be found in the tree.The argument inside those sentences is worth keeping and does not need the history: each mirror authors its own hook manifest, and that is not a duplicate because this repository serves no hook ids and the two id sets are disjoint, so a derivation would have nothing to keep in step. Stated that way it answers the question a reader actually has — why aren't these derived from one file? — instead of the question of what changed.
Two smaller cuts of the same kind in
CLAUDE.md: anowthat dated the sentence about themirror-diffwindow, and a clause naming the last file to have carried aDEVIATIONcomment, which the sentence immediately before it already covers by saying none does.Verification
The generator's output is unchanged:
Corpus
The corpus is the specification, and both implementations answer to it. Tick what applies.
corpus/pins the new behavior. The case was written first and failed first.A docstring and two
CLAUDE.mdsentences. No_TEMPLATED,_VERBATIMor code-path change — the fifth file was always emitted, only unlisted.Checks
make checkpasses, ormake testdoes and this touches no Rust.make tidy— ruff, mypy, markdownlint and both spell gates — plusunwrap-markdown-prose-py --fail-on-change CLAUDE.md, and the generator run above.