Skip to content

feat(bug): move bug reporting to /bug/ and list every project's tracker - #167

Merged
sanity merged 4 commits into
mainfrom
bug-report-page
Sep 3, 2026
Merged

feat(bug): move bug reporting to /bug/ and list every project's tracker#167
sanity merged 4 commits into
mainfrom
bug-report-page

Conversation

@sanity

@sanity sanity commented Sep 3, 2026

Copy link
Copy Markdown
Contributor

Problem

Freenet has no memorable URL for "where do I report a bug". A page does exist,
added in #120, but it lives at /community/support/, which nobody guesses and
which reads like a help desk rather than an issue tracker index.

It also stops short of a full list. It triages the four things most people are
using (River, Freenet itself, this website, Ghost Keys) and then names six other
apps in a sentence. The libraries and developer tools have no entry at all, so a
bug in freenet-stdlib or freenet-migrate has no signposted destination.
There is nothing about security vulnerabilities either, and a public issue for
an unfixed hole is a working attack recipe.

Approach

One page, not two. Rather than add a second bug page at /bug/ and leave two
competing versions to drift apart, this moves the existing page there and keeps
/community/support/ and /community/get-involved/ as aliases, adding /bugs/,
/report/ and /community/ alongside them, so every existing link still
resolves. The homepage, quickstart and footer links are repointed to the short
URL.

Three additions to the page itself:

  • A table of every project you can file against, 19 rows, most-starred
    first. Each name links to that project's issue list, so a reader can check
    whether their bug is already there. It sits below the "what were you using?"
    triage, which stays the primary route: the table is the reference list for the
    cases triage doesn't name.
  • A security callout, routing vulnerabilities to freenet-core's private
    advisory form with an email fallback for anyone without a GitHub account, and
    saying explicitly that the public Matrix room is not the place for them.
  • A cross-reference from the "one of the other apps" section down to the table.

Repos left out of the table are internal build and test infrastructure
(portal, websitemirror, freenet-test-network), dormant (kweb-up-poc,
freenetorg-website, which is archived), or have issues switched off
(blindsign, freenet-scaffold-macro). paper-1 is included: it is public,
accepts issues, and is the source of the whitepaper this site publishes.

One judgment call worth flagging: the table is two columns, not three. A
third "New issue" column pushed the table into horizontal scroll on a 390px
viewport, which put the primary action off-screen on a phone. Linking the
project name to the issue list instead keeps the whole table on screen at every
width, and works for a logged-out reader, which /issues/new does not.

Review

Four independent passes: code-first and skeptical Claude reviewers, an external
codex review, and a verification pass over the resulting fixes. They found
eleven real problems, including one that mattered: the security callout
originally left a reporter without a GitHub account with only the public Matrix
room, which this page's own text three lines above recommends. All are fixed;
the two consolidated review comments below record each finding and where it
landed. The final external pass reports no regressions.

Testing

  • hugo builds clean, no warnings.
  • python3 scripts/check-links.py passes: no broken internal links, 224 pages.
    Its self-test passes too, so the green is not vacuous.
  • All five aliases confirmed redirecting to /bug/ in the built output, and
    /community/ no longer publishes an empty section page or an empty feed.
  • All 19 linked repos checked via the GitHub API: public, unarchived, issues
    enabled, no issue template that would divert the link, and every URL returns
    200 anonymously.
  • The security callout verified in the built HTML: clean prose, no leftover
    script, and a usable address with JavaScript disabled.
  • Rendered at 1280px and 390px; no horizontal overflow at either width.

There is a separate theme bug this change worked around rather than fixed: the
breakout rule at base.css:337 that should let wide tables extend past the
prose column never takes effect, because max-width: 100% at base.css:811
clamps it. Filed as #168 rather than fixed here, since it changes how tables
render on other pages and deserves its own visual review.

https://claude.ai/code/session_016G7mL6JBHFqXJf7SksY631

[AI-assisted - Claude]

The bug-reporting page lived at /community/support/, a URL nobody guesses.
Move it to /bug/, keeping the old path plus /bugs/ and /report/ as aliases,
and repoint the homepage, quickstart and footer links.

Add a complete table of every public project's issue tracker, largest first
by stars, so a report about a project the triage section doesn't name has an
obvious destination. Add a note on where security vulnerabilities go, since
a public issue for an unfixed hole is a working attack recipe.

Private vulnerability reporting is only enabled on freenet-core and raven,
so the security note points everyone at freenet-core's advisory form rather
than at "the relevant repository", which would dead-end on the other 16.

Repos left out of the table are internal build and test infrastructure
(portal, websitemirror, freenet-test-network, paper-1) or have issues
disabled (blindsign, freenet-scaffold-macro).

Claude-Session: https://claude.ai/code/session_016G7mL6JBHFqXJf7SksY631
sanity added a commit that referenced this pull request Sep 3, 2026
Moving the support page out of content/community/ left the section's
title-only _index.md behind, so /community/ rendered as a "Community"
heading with no children. Delete it and alias /community/ to /bug/.

Found by codex review on #167.

Claude-Session: https://claude.ai/code/session_016G7mL6JBHFqXJf7SksY631
Moving the support page out of content/community/ left the section's
title-only _index.md behind, so /community/ rendered as a "Community"
heading with no children. Delete it and alias /community/ to /bug/.

Also gitignore hugo-site/public_review, a build output directory that
is not covered by the existing hugo-site/public entry.

Found by codex review on #167.

Claude-Session: https://claude.ai/code/session_016G7mL6JBHFqXJf7SksY631
From the code-first and skeptical review passes on #167:

- The security callout gave a reporter without a GitHub account no private
  route, three lines below telling them to use the public Matrix room. Add an
  email fallback and carve security reports out of the Matrix advice.
- "whichever project it affects" invited a reporter to try
  <repo>/security/advisories/new by analogy. Private vulnerability reporting is
  enabled only on freenet-core, so those 404 and push the reporter back to a
  public issue form. Name freenet-core explicitly as the one private channel.
- Soften "we'll credit you when the fix ships" to match what SECURITY.md
  actually promises: acknowledgement and coordinated disclosure.
- Link each table row to the project's issue list rather than its new-issue
  form. /issues/new 302s a logged-out reader to a login page with no way back,
  so the "check whether yours is already there" advice dead-ended.
- Add paper-1. It is public, accepts issues, and is the source of the
  whitepaper this site publishes, so it is not the build infrastructure the
  closing sentence claimed. Reword that sentence to cover dormant experiments
  and issues-disabled crates too.
- "largest project first" was false by every size metric; the order is by
  stars. Say so.
- llms.txt still pointed at /community/get-involved/ labelled "how to
  contribute", which now redirects to a bug-report page. Replace with /bug/.

Claude-Session: https://claude.ai/code/session_016G7mL6JBHFqXJf7SksY631
@sanity

sanity commented Sep 3, 2026

Copy link
Copy Markdown
Contributor Author

Review summary

Risk tier: Light (content page, no code paths). Ran three independent lenses on
the diff: code-first and skeptical Claude reviewers, both blind to each
other, plus the external non-Claude pass (codex review --base origin/main).
All three found real problems. Every finding below is fixed in 5dda2df unless
marked otherwise.

Fixed

# Finding Lens
1 Security callout left a reporter without a GitHub account with only a public route. Three lines above it, the page says "no GitHub account? tell us in Matrix" — a public room. So the page's own instructions handed someone a 0-day disclosure path. Added an email fallback and carved security reports out of the Matrix advice. skeptical, code-first
2 "whichever project it affects" invited a reporter to try <repo>/security/advisories/new by analogy with every other row. Private vulnerability reporting is enabled on only 2 of the 18 repos, so those 404 and the likely fallback is the public issue form. Now names freenet-core explicitly as the one private channel. skeptical, code-first
3 Moving the only child out of content/community/ left /community/ publishing an empty section page and an empty RSS feed, both still in the sitemap. Deleted the stub and aliased /community/ to /bug/. codex, skeptical, code-first
4 Table rows linked to /issues/new, which 302s a logged-out reader to a login page with no repo nav. The instruction to "read what has already been filed" dead-ended for exactly the people most likely to follow it. Rows now link to /issues, which is public and carries the New issue button. code-first, skeptical
5 paper-1 was omitted, and the closing sentence called every omission "internal build and test infrastructure". It is public, accepts issues, and is the source of the whitepaper this site publishes and the deploy workflow downloads. Added to the table; sentence reworded to cover dormant experiments and issues-disabled crates. skeptical, code-first
6 "largest project first" is false by every size metric (mail has 231 commits and sits 6th; freenet-git has 80 and sits 4th). The order is by stars. Now says so. code-first, skeptical
7 "We'll credit you when the fix ships" is a stronger promise than SECURITY.md makes, and credit only materialises if the advisory is published. Softened to match. code-first, skeptical
8 llms.txt still pointed at /community/get-involved/ labelled "how to contribute", which now redirects here. Replaced with a /bug/ entry. code-first, skeptical

Also caught in passing: a git add -A of mine had swept 2452 files of build
output into a commit. Removed, and hugo-site/public_review is now gitignored.

Not fixed, deliberately

  • Repo slugs in the table vs product names in the prose (ghostkeys vs
    "Ghost Keys"). The slug is what identifies the tracker, and the adjacent
    "what it covers" column carries the product name. Left as is.
  • The table duplicates links from the triage sections above. True, and
    nothing keeps them in sync. The triage section is the route for the common
    cases and the table is the complete reference; collapsing either loses
    something. Worth a maintainer's eye if they drift.
  • Wide-table CSS breakout is broken in the theme (base.css:337 is clamped
    by max-width: 100% at base.css:811). Filed as fix(theme): wide tables never break out of the prose column #168 rather than fixed here,
    since it changes table rendering on other pages and wants its own visual check.

Open question for a maintainer

Private vulnerability reporting is enabled on freenet-core and raven only.
Enabling it across the other 16 repos would let this page give per-project
advice instead of routing everything through freenet-core. Not done here, since
it is a settings change rather than a content one.

Verification

hugo builds clean; scripts/check-links.py passes (224 pages, no broken
internal links or dead anchors); all 19 linked repos confirmed public,
unarchived and issues-enabled via the GitHub API, with no issue template that
would divert /issues/new; all five aliases confirmed redirecting to /bug/
in the built output; rendered at 1280px and 390px with no horizontal overflow
at either width. The freenet service report claims on the page were checked
line by line against freenet-core's commands/report.rs by both reviewers and
hold, including the 60-second worst case and the report-code charset.

[AI-assisted - Claude]

From the verification review pass on #167:

- email-protect emits block-level HTML, and the alert shortcode runs its inner
  text through markdownify, so nesting the two split the sentence across three
  rendered paragraphs: "...without one, email" / the address / "instead. We'll
  acknowledge...". Spell the address out inline instead. That survives
  markdownify, needs no JavaScript, and gives a reporter browsing with scripts
  off an actual route rather than "[Enable JavaScript to see email]" — which
  matters here, since the same callout forbids the public Matrix room and the
  GitHub form needs an account.

- "It is the one private channel, and the other repositories have no equivalent
  form" was false: private vulnerability reporting is enabled on raven as well
  as freenet-core. Say that reports for every project are handled at freenet-core
  instead, which is true and is the part the reporter needs.

- "The complete list" and the omitted-repos sentence still overstated. The table
  lists every project you can file against, not every repo, and freenetorg-website
  is archived rather than infrastructure or a dormant experiment.

- llms.txt advertised /resources/why-freenet/, whose source is draft: true, so
  the URL 404s. Removed. Pre-existing, but this PR is the one editing that file.

Claude-Session: https://claude.ai/code/session_016G7mL6JBHFqXJf7SksY631
@sanity

sanity commented Sep 3, 2026

Copy link
Copy Markdown
Contributor Author

Second review round

Re-ran the review on the changed content, since the first round's fixes were
themselves new content. A verification lens plus the external pass found two
real defects in the fixes, both now corrected in 92925c9.

1. The security callout rendered broken. email-protect emits block-level
HTML, and alert runs its inner text through markdownify, so nesting the two
split one sentence across three paragraphs in the built output:

<p>...without one, email</p>
<p><span id="ep-85d90cc5"></span></p>
<script>...</script>
<p><noscript>[Enable JavaScript to see email]</noscript>
instead. We'll acknowledge your report...</p>

Worse than cosmetic: the no-JS reader saw [Enable JavaScript to see email] and
no address, in a callout that had just told them not to use the public Matrix
room and that the GitHub form needs an account. Every route closed. Now the
address is spelled out inline, which survives markdownify and needs no
JavaScript. Verified in the built HTML: two clean paragraphs, zero <script>.

2. "It is the one private channel" was false. Private vulnerability
reporting is enabled on raven as well as freenet-core. The wording that
replaced an inaccurate claim in round one introduced a different one. Now says
reports for every project are handled at freenet-core, which is true and is the
part a reporter needs.

Also in this round: "The complete list" narrowed to "every project you can file
against" (7 public repos are legitimately omitted), the omitted-repos sentence
corrected again for freenetorg-website (archived, not infrastructure or a
dormant experiment), and a dead entry removed from llms.txt pointing at
/resources/why-freenet/, whose source is draft: true so the URL 404s. That
last one is pre-existing and unrelated, fixed here only because this PR is what
touches the file.

External pass (codex review --base origin/main) re-run on the final content:
no regressions found.

Verified again after the changes: hugo builds clean, check-links.py passes
(224 pages), no horizontal overflow at 1280px or 390px.

[AI-assisted - Claude]

@sanity
sanity merged commit 5346aee into main Sep 3, 2026
3 checks passed
@sanity
sanity deleted the bug-report-page branch September 3, 2026 01:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant