Repository navigation
Check the site before it is served - #2
Merged
Merged
Conversation
The site had no gate at all. Nothing builds it, so a link that resolves to
nothing, an asset that was removed or an external link over plain HTTP went
straight to the public page with nobody in the way. Every other repository in
the organization has a required check; this one is the most visible and had
none.
tools/sitecheck.py is what a build step would have done:
* every internal link resolves to a file in the repository;
* every fragment names an id that is on the page it names, including a
fragment of another page, which is what rots silently when a heading is
renamed;
* every referenced asset exists, and every asset in the tree is referenced,
including the social card of the og:image and twitter:image meta tags,
which a crawler fetches and a reader never sees fail;
* an external link is https or mailto;
* a page carries a language, a title and exactly one h1.
It is a pure function of a mapping of path to text, so each rule is tested as
the smallest page that breaks it, and the suite ends by running the checker
over this repository: the rules are only worth having if the site satisfies
them.
Two findings came out of the first run, both real. The dark and the one
colour marks were served and referenced by nothing, so guidelines.html now
has a section for the mark that offers all four variants with the rules for
using them, which is what a brand page is for.
Measured: 37 tests, tools/sitecheck.py 99 percent lines and branches, against
the 95 the project asks of its own code.
The gate failed on its first run, correctly, and on something the local run could not see: in CI the editable install writes *.egg-info/SOURCES.txt and its siblings into the tree, and a .txt is something a site can legitimately serve, so three packaging files were counted as assets no page references. A suffix rule alone cannot tell them apart, so the tree now says which directories are the site: this checker, its tests, and the directories a tool leaves behind are not, including anything ending in .egg-info or .dist-info. Tested against a fixture tree carrying all four. .gitignore keeps the same leftovers out of the repository.
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.
The site had no gate. Nothing builds it, so a link that resolves to nothing,
an asset that was removed or an external link over plain HTTP went straight to
the public page with nobody in the way. It is the most visible repository in
the organization and the only active one with no required check.
tools/sitecheck.pydoes what a build step would have done: internal linksresolve, fragments name ids that exist (including on another page), every
referenced asset exists and every asset is referenced (counting the
og:imageand
twitter:imagecards a crawler fetches), external links are https ormailto, and each page has a language, a title and exactly one h1.
Two findings from the first run were real: the dark and one-colour marks were
served and referenced by nothing.
guidelines.htmlnow has a section for themark offering all four variants with the rules for using them.
Test plan
fails on a real broken link rather than only on a unit case.
tools/sitecheck.py99 percent lines and branches, against the 95 theproject asks of its own code.
python3 tools/sitecheck.py .exits 0 on this branch: 2 pages, 7 assets,0 findings.
python / coveragerequired onmain.