docs(readme): link absolutely for the registries - #41
Merged
Conversation
`readme = 'README.md'` in both manifests makes this file the project description on PyPI and on crates.io, and PyPI passes a relative href through without rewriting it. So every relative link in this file resolved against the project page there rather than against the repository, and the live 0.4.0 description carries eight of them: the whole Documentation list, both badge targets, and the benchmark link in the opening section. A consumer arriving from `pip install` followed each of them to a page that does not exist. The eight are now absolute, which is the form crates.io already generates for them and which GitHub renders unchanged, so one file serves all three surfaces. The two in-page anchors stay relative because they resolve inside whichever page is rendering them. The cost is that a link followed from an older release's page shows the current `main` rather than the tree that release shipped. That is the better failure: a stale-but-present page against a 404, and the mirror readmes already link upstream this way for the same reason. Found by checking the published description rather than the source: the PyPI JSON for 0.4.0 lists all eight targets with `description_content_type: text/markdown`. 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 QodoUse absolute README links across package registries
AI Description
Diagram
High-Level Assessment
Files changed (1)
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #41 +/- ##
=======================================
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 readme tells a consumer to move their `rev:` pin to follow a newer release, and no document said where to read what changed between the version they hold and the one they are moving to. The releases page is the only record -- generated from the merged pull requests, since nothing here writes a changelog -- and it was named nowhere: not in this file, not in SECURITY.md, CONTRIBUTING.md or either mirror readme. So the Documentation list gains it, beside the four documents that were already there. It belongs at the top of that list rather than the bottom, because moving a pin is the most common thing a consumer of this repository does. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
The change is limited to README link targets and cleanly resolves registry rendering issues without affecting tool behavior.
Pull request overview
This PR updates the repository README (which is used as the project description on PyPI and crates.io) to avoid broken navigation from those registries by converting file-relative links into absolute GitHub blob/main/ URLs.
Changes:
- Replace README links to repository files (e.g., CONTRIBUTING, LICENSE, SECURITY, docs) with absolute GitHub URLs so they resolve correctly on PyPI/crates.io.
- Add a “Releases” entry to the Documentation section to provide a stable, registry-friendly changelog pointer.
File summaries
| File | Description |
|---|---|
| README.md | Converts relative file links to absolute GitHub URLs so the README renders with working links on PyPI and crates.io. |
Review details
- Files reviewed: 1/1 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
Both manifests set
readme = 'README.md', so this file is the project description on PyPI and on crates.io. PyPI's renderer passes a relative href through without rewriting it, so every relative link in the README resolves againsthttps://pypi.org/project/markdown-prose-hooks/rather than against the repository.Checked against the published description rather than inferred from the source:
Eight file targets, live on the 0.4.0 page: the whole Documentation list, both badge targets (PRs-welcome and License), and the benchmark link in the opening section. A consumer arriving from
pip installfollows each of them to a 404.The eight are now absolute
blob/main/URLs — the form crates.io already generates for them, and the form GitHub renders unchanged — so one file serves all three surfaces. The two in-page anchors stay relative, because they resolve inside whichever page renders them.The trade-off, stated: a link followed from an older release's PyPI page now shows current
mainrather than the tree that release shipped. That is the better of the two failures — a stale-but-present page against a 404 — and it is what the mirror readmes already do (mirrors/py/README.md:7links upstream absolutely for the same reason).This is worth landing before the next release, since the next publish is what refreshes the description.
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.Checks
make checkpasses, ormake testdoes and this touches no Rust.make tidy— markdownlint, prettier and both spell gates — plusunwrap-markdown-prose-py --fail-on-change README.md. One Markdown file; no relative file target remains.