📦 WP-113b — feat(scripts): absolute README links for PyPI¶
Engineering log · Phase 11 — Rolling, toward v0.5.0
🔗 Depends on WP-067 · Needed by none
WP-113b — a README cannot be relative in two places at once¶
pyproject.toml hands README.md to setuptools as the long description, and PyPI resolves its relative targets against pypi.org: the three training-curve figures render as broken images and every docs/… link 404s. The same file has to stay relative in the git tree, where relative is exactly what works. So the rewrite belongs to the moment of packaging rather than to the file, and it is opt-in per invocation — --ref v0.4.0 or LUCID_YOLO_RELEASE_REF — so an ordinary make build or a pip install . cannot reach it.
Two hosts, because the two link classes fail differently. A figure served through github.com/.../blob renders an entire HTML page inside an <img>, which is a broken image; a document served through raw.githubusercontent.com hands the reader unrendered markdown. Images therefore resolve through raw, documents through blob, and the classifier keys on the markdown image bang or the target's suffix, since an HTML <img src=> carries no bang.
A branch may not be pinned. A released wheel's README is a snapshot of one tree, and a link into main describes whatever that branch holds when a reader clicks it — which is how a page for 0.4.0 ends up documenting code that shipped years later. Only a v0.MINOR.PATCH tag or a full commit sha is accepted.
The slug is read from project.urls.Homepage, and reading it exposed a live defect. The declared homepage was Borda/lit-YOLOs; the repository's canonical full_name is Borda/lucid-YOLO. GitHub redirects a renamed repository's HTML URLs, so the stale slug looks fine in a browser and every blob link would have worked — but raw.githubusercontent.com does not redirect, so precisely the three figures this package exists to publish would have 404'd, while the links beside them resolved. A rename is invisible until something reads the metadata programmatically.
What the tests cannot establish is whether the produced URLs resolve. The repository is private at the time of writing, so every generated link 404s for an anonymous reader regardless of correctness; the URLs become true when the repository is public and the tag exists. That is stated rather than asserted, because a test that fetched them would be a test of the repository's visibility settings.