Open the README with a sync diagram and a shorter badge row - #59
Merged
Conversation
Show uv.lock feeding .pre-commit-config.yaml, with the rev lines rendered as a diff. The example keeps ruff's leading v and drops it for black, to make the per-repo version template visible at a glance. Keep the SVG as the editable source and commit a 2x PNG beside it: PyPI does not render SVG in the long description, and README.md is the project's long description. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YUykXbniqe4c2eLNtwVqx6
State what the tool does in one line before the badges, and place the diagram above the Overview so the first screen shows a real rev update rather than prose alone. Reference the PNG by absolute URL: README.md is also the PyPI long description, where relative paths do not resolve. The image therefore renders only once this lands on main. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YUykXbniqe4c2eLNtwVqx6
Drop the uv, Ruff and Black badges: they advertise the dev toolchain rather than telling a prospective user anything about installing this. Drop PyPI platforms and PRs Welcome too, the latter being covered by CONTRIBUTING.md. Let the remaining badges reflow as one row instead of forcing a 4/2 split, and remove the link definitions left unreferenced. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YUykXbniqe4c2eLNtwVqx6
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #59 +/- ##
=======================================
Coverage 98.80% 98.80%
=======================================
Files 5 5
Lines 250 250
Branches 44 44
=======================================
Hits 247 247
Misses 2 2
Partials 1 1 ☔ View full report in Codecov by Harness. |
A raw.githubusercontent URL always resolves to main, so the image never renders on a branch or in a pull request. A relative path renders everywhere the repository is checked out. This does mean the image no longer renders on PyPI, which does not resolve relative paths in the long description. The title and tagline are plain text, so the page still reads without it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YUykXbniqe4c2eLNtwVqx6
Keep the tagline and the diagram adjacent, so the value statement is followed straight away by proof of it. The badges are metadata rather than part of that pitch, and reach the reader just as well once the first screen has done its work. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YUykXbniqe4c2eLNtwVqx6
Share one centre axis with the diagram above it, instead of the badges sitting hard left under a centred image. The blank lines inside the <p> are required: without them GitHub treats the badge list as raw HTML and prints it literally. mdformat preserves them, and GitHub's own renderer confirms all six resolve to images. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YUykXbniqe4c2eLNtwVqx6
This reverts commit c4e0fe5.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 1 issue, and left some high level feedback:
- The README currently references
./assets/readme/sync-flow.png, but the description mentions using an absoluteraw.githubusercontent.com/.../main/...URL for PyPI; double-check that the final README link matches the intended strategy so the image renders correctly both on GitHub and on PyPI. - If the PNG diagram is meant to render when viewing the project from an sdist or wheel (e.g., on PyPI or in offline docs), ensure
assets/readme/sync-flow.png(and the SVG, if needed) are included in the package data/MANIFEST so the path remains valid.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The README currently references `./assets/readme/sync-flow.png`, but the description mentions using an absolute `raw.githubusercontent.com/.../main/...` URL for PyPI; double-check that the final README link matches the intended strategy so the image renders correctly both on GitHub and on PyPI.
- If the PNG diagram is meant to render when viewing the project from an sdist or wheel (e.g., on PyPI or in offline docs), ensure `assets/readme/sync-flow.png` (and the SVG, if needed) are included in the package data/MANIFEST so the path remains valid.
## Individual Comments
### Comment 1
<location path="README.md" line_range="163-164" />
<code_context>
Interested in contributing?
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guideline.
-[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
</code_context>
<issue_to_address>
**suggestion (typo):** Consider changing "guideline" to "guidelines" for correct grammar.
Using the plural "guidelines" here would read more naturally and align with standard documentation phrasing.
```suggestion
Interested in contributing?
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Comment on lines
163
to
164
| Interested in contributing? | ||
| See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guideline. |
There was a problem hiding this comment.
suggestion (typo): Consider changing "guideline" to "guidelines" for correct grammar.
Using the plural "guidelines" here would read more naturally and align with standard documentation phrasing.
Suggested change
| Interested in contributing? | |
| See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guideline. | |
| Interested in contributing? | |
| See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines. |
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
1 participant
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.
Gives the README a visual first screen without touching its structure. Everything from
## Overviewdown is unchanged.What changed
assets/readme/sync-flow.svg+ a 2x PNG) showinguv.lockfeeding.pre-commit-config.yaml, with therevlines as a diff. It was built from real--diffoutput, and the example deliberately keeps ruff's leadingvwhile dropping it for black, so the per-repo version template is visible at a glance.Net: 8 insertions, 16 deletions. The README is shorter than before.
Two things worth a look
The image will not render in this PR. It is referenced by absolute
raw.githubusercontent.com/.../main/...URL, which always resolves tomain, never this branch. That is deliberate:README.mdis also the PyPI long description, where relative paths do not resolve and SVG is not rendered at all. It starts rendering once this merges. Preview it locally withrsvg-convert -w 440 assets/readme/sync-flow.svg -o /tmp/preview.png.Discussions is enabled but has 0 threads. I kept the badge because PRs Welcome is going away and it becomes the only "where do I ask?" signal, but it does currently point at an empty page. Easy to drop.
Verified
prekpasses on every commit, and the diagram was checked at its true 440px display size on both light and dark GitHub backgrounds.🤖 Generated with Claude Code
https://claude.ai/code/session_01YUykXbniqe4c2eLNtwVqx6