Repository navigation
docs: badge row, and a test that the links in it are real - #7
Merged
Merged
Conversation
Four badges, each pointing at something a developer wants before reading prose: the CI workflow, the research repository, the paper, and the licence. "Powered by REMORA" became a sentence that says what the relationship actually is — consumed as a hash-pinned release, not a dependency on master. ## The test is the interesting half A dead link on a public front page reads as neglect of everything behind it. The specific hazard here has already bitten once: docs/ARCHITECTURE.md and docs/architecture.md are the same file on Windows and two different files on the Linux host GitHub serves from, so three links resolved perfectly for the person who wrote them and would have 404'd for every reader. test_readme_links.py checks every relative link in every document against the real directory listing, component by component. The first version of it did not work, and failed in exactly the way it was meant to prevent. It called Path.resolve(), which on Windows canonicalises a path to the real on-disk spelling — so docs/ARCHITECTURE.md came back as docs/architecture.md and the check validated the lookup rather than what was written. Verified by deliberately breaking a link: the first version passed 24/24, the rewrite fails on precisely that link and passes when it is restored. Also checks that a CI badge names a workflow that exists (a badge for a missing workflow renders as "no status" and reads as a broken build), and that no document is unreachable from the README. Filesystem only: no network, no Docker, part of the fast gate.
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.
Four badges at the top of the README — CI, the research repository, the paper, and the licence — so a developer sees what this is built on before any prose. "Powered by REMORA" became a sentence that states the actual relationship: consumed as a hash-pinned release, not a dependency on its
master.The test is the interesting half
A dead link on a public front page reads as neglect of everything behind it, and the specific hazard here has already bitten once:
docs/ARCHITECTURE.mdanddocs/architecture.mdare the same file on Windows and two different files on the Linux host GitHub serves from. Three links resolved perfectly for the person who wrote them and would have 404'd for every reader.test_readme_links.pychecks every relative link in every document against the real directory listing, component by component.The first version of it did not work — and failed in exactly the way it was written to prevent. It called
Path.resolve(), which on Windows canonicalises a path to the real on-disk spelling, sodocs/ARCHITECTURE.mdcame back asdocs/architecture.mdand the check validated the lookup rather than what was written.Verified by deliberately breaking a link:
It also asserts that a CI badge names a workflow that exists — a badge for a missing workflow renders as "no status" and reads as a broken build — and that no document is unreachable from the README.
Filesystem only: no network, no Docker, part of the fast gate. 95 contract tests pass.
Note on ordering
Branched from
mainso the badges can land without waiting on #6. #6 also touches the README; I will mergemaininto it once this lands so it stays mergeable.