Decision / Feedback: Adopt bruce in CI? #69
Labels
No labels
Contributors' Guidance
Improve written Material
Contributors' Guidance
technical support measures
effort
high
effort
low
effort
medium
good first issue
help wanted
meeting topic
needs changes
needs reporter feedback
needs review
needs vote
priority
high
priority
low
priority
medium
priority
on hold
type/content
type/misc
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
docs/tickets#69
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
What is bruce?
bruceis a tool I've created (still WIP) to crawl sites like docs.fp.o and produce reports on broken links. What's unique is that bruce can report links to a broken anchor, e.g.https://example.com/foo#this_anchor_doesnt_exist. This surfaces issues where we linked to a specific section on a page, and then that section went away. The URL is not 404, but the content is gone.There are >700 such links currently across our docs -- almost as many of these as actual 404 links (>800).
You can see some example reports at https://mwinters.fedorapeople.org/bruce/ . The tool is still WIP, so newer reports look better than old ones, but I think they are useful enough now to be actionable. The underlying data is also available as json and duckdb for further tinkering.
My plan / request
Phase 1
Phase 2
Update the tool so that it can automatically file "broken link" issues in the Forge repos. The tool must also be capable of detecting when a link is no longer broken and automatically closing these automatically-created issues, so that they are helpful instead of annoying.
If our AI folks wanted to, this would provide an easy index for some other bot to discover such issues and propose PRs.
Phase "maybe someday"
Since the tool builds a central database, it would be possible to configure each docs repo with a lint step in CI which checks the central database, to see whether the current commit contains broken links and either warn or prevent the commit.
The difficult part is not building this step, it's the fact that if you applied it today it would warn/block almost every single repo: 83% of them have broken links today. So each repo would need to fix all of their links first to get to green.
How to read the report (FAQ)
I'll continue to update this issue as questions come up, and I'll incorporate these docs directly into the report.
What does "broken through" and/or "doubled slash" mean?
We have a situation where page B is fine if you go there the right way, but page A links to it in a way that adds an extra slash, e.g.
docs.fp.o/foo//page_B/ordocs.fp.o/foo/page_B//.If you navigate from A -> B, page B will work but all of its relative links (
../../blah) are broken because of the extra slash in the path. I didn't want to count these numbers against page B, because there's nothing wrong there -- the problem is in page A. This is labeled as "broken through it" if the slash is in the middle of the URL, and "doubled slash" if the slash is at the end.What is a "pedantic" error?
Humans generally write URLs like
example.com/foobut technically the correct form isexample.com/foo/-- notice the trailing slash. These are actually two separate web pages as far as most web servers are concerned, and if you visit the first one the web server will helpfully tell your browser, "Hey dummy, there's no page here it's over at example.com/foo/". So your browser has to make a second request.Should we count the "wrong" URL as broken, considering that the user eventually ends up in the right place? It's debatable, but certainly lower priority than actually-broken links (e.g. 404). These are not currently marked as broken, landing instead under Housekeeping as "pedantic".
Discussed at the 2026-11-03 team meeting: https://discussion.fedoraproject.org/t/fedora-docs-team-meeting-2026-11-03/206179/2
My near-term roadmap then:
/static/