From aaa0d3ed61b9d199d8c74be793bbffe6b6ac222e Mon Sep 17 00:00:00 2001 From: Ian Clarke Date: Tue, 25 Aug 2026 09:21:38 -0500 Subject: [PATCH 1/3] feat: give users a signposted route to report a bug ## Problem An ordinary user on freenet.org who hits a bug has nowhere correct to go. Concretely, on the live site today: - The strings "report a bug", "file an issue" and "bug report" appear nowhere in the site's content or templates. - The only GitHub link in the footer is the "src: freenet/web" credit, so the single most obvious place a user would click routes every River bug and every node bug into the *website's* tracker. - /community/support/ and /community/get-involved/ are published but completely empty (title front matter, no body). Quickstart's "What's Next" list links to the latter, so the one navigational promise of a community route is a blank page. - Nothing anywhere states which repo covers what. /apps/ links ten repos, but as project homepages, not as "report bugs here". Freenet spans freenet-core, river, web, ghostkeys and the rest, so "file an issue" is ambiguous even for someone willing to look. ## Approach Fill the existing empty /community/support/ page with a routing page that sorts a reporter by what they were doing, rather than adding new scaffolding. It covers River, the node itself, the website, Ghost Keys, other apps, and an explicit "Not sure" route (freenet-core, which the maintainers watch most and can move a report from). It says plainly that filing on GitHub needs a GitHub account, and offers Matrix as the route for people who do not want one. It also documents `freenet service report`, which produces a report code maintainers can look up, along with `--local` for anyone who would rather inspect the bundle before uploading it. Discovery: one footer link, present on every page, plus an entry in the homepage's secondary-links row and in Quickstart's Troubleshooting and "What's Next" sections, which is where a struggling user already is. The empty get-involved stub is deleted; /community/get-involved/ and a new short /report/ both alias to the page, so the Quickstart link that previously dead-ended now lands somewhere real. ## Testing - `hugo` builds clean; `scripts/check-links.py` reports no broken internal links across 223 pages. - Alias redirects verified in the built output for /report/ and /community/get-involved/. - All five external GitHub targets return 200. - Rendered and screenshotted at 1200px and 390px, light and dark palettes covered by the CSS. [AI-assisted - Claude] --- hugo-site/content/_index.md | 3 +- .../content/community/get-involved/index.md | 5 - hugo-site/content/community/support/index.md | 106 +++++++++++++++++- hugo-site/content/quickstart/_index.md | 4 +- .../themes/freenet/assets/css/freenet.css | 37 ++++++ .../freenet/layouts/partials/footer.html | 3 + 6 files changed, 148 insertions(+), 10 deletions(-) delete mode 100644 hugo-site/content/community/get-involved/index.md diff --git a/hugo-site/content/_index.md b/hugo-site/content/_index.md index 0fe488f2..c987150f 100644 --- a/hugo-site/content/_index.md +++ b/hugo-site/content/_index.md @@ -131,6 +131,7 @@ just a few hops, scaling efficiently to millions of peers, no servers required. [River](/river/) · [Apps](/apps/) · [Video Talks](/about/video-talks/) · [Matrix Chat](https://matrix.to/#/#freenet-locutus:matrix.org) · -[GitHub](https://github.com/freenet/freenet-core) · [FAQ](/about/faq/) +[GitHub](https://github.com/freenet/freenet-core) · [FAQ](/about/faq/) · +[Report a Bug](/community/support/) diff --git a/hugo-site/content/community/get-involved/index.md b/hugo-site/content/community/get-involved/index.md deleted file mode 100644 index 20ce255e..00000000 --- a/hugo-site/content/community/get-involved/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "Get Involved" -date: 2024-06-11T00:00:00Z -draft: false ---- diff --git a/hugo-site/content/community/support/index.md b/hugo-site/content/community/support/index.md index db845062..0ada3ee5 100644 --- a/hugo-site/content/community/support/index.md +++ b/hugo-site/content/community/support/index.md @@ -1,5 +1,107 @@ --- -title: "Support" -date: 2024-06-11T00:00:00Z +title: "Report a Bug or Get Help" +description: + "Where to report a Freenet bug or ask for a feature: which project, which issue tracker, and what + to include." +date: 2026-08-25 draft: false +aliases: + - /report/ + - /community/get-involved/ --- + +Found a bug, or want something Freenet does not do yet? Please tell us. This page points you at the +right place to say it. + +Freenet is a network plus a set of separate apps built on top of it, and each one keeps its own list +of bugs. So the first step is picking which one you were using. If you pick wrong we will move your +report for you, so it is not worth agonising over. + +{{< alert type="warning" >}} **Filing a report on GitHub needs a free GitHub account.** If you would +rather not create one, say it in [our Matrix room](https://matrix.to/#/#freenet-locutus:matrix.org) +instead and someone will file it for you. {{< /alert >}} + +## What were you using? + +### Group chat (River) + +Messages not sending, a room that will not load, an invite that does not work, members missing, +anything in the chat interface itself. + +→ [Report a River bug](https://github.com/freenet/river/issues/new) · +[existing River issues](https://github.com/freenet/river/issues) + +### Freenet itself + +Install or uninstall trouble, the node will not start or will not stay running, no connections, high +CPU or bandwidth use, the menu bar or system tray icon, errors from the `freenet` command. Anything +underneath the apps rather than inside one. + +→ [Report a Freenet bug](https://github.com/freenet/freenet-core/issues/new) · +[existing Freenet issues](https://github.com/freenet/freenet-core/issues) + +### This website + +A broken link, documentation that is wrong or confusing, a page that will not load, a typo. + +→ [Report a website bug](https://github.com/freenet/web/issues/new) · +[existing website issues](https://github.com/freenet/web/issues) + +### Ghost Keys + +Anything about donations, Ghost Key certificates, or the vault. + +→ [Report a Ghost Keys bug](https://github.com/freenet/ghostkeys/issues/new) · +[existing Ghost Keys issues](https://github.com/freenet/ghostkeys/issues) + +### One of the other apps + +Delta, Mail, freenet-git, Atlas and the rest each keep their own list. Every app on the +[apps page](/apps/) links to its own project, and you will find its issues there. + +### Not sure + +Use the [Freenet issue tracker](https://github.com/freenet/freenet-core/issues/new). It is the one +the maintainers watch most closely, and they will move your report if it belongs somewhere else. +Describing clearly what happened matters far more than landing it in the right place first time. + +If you would rather have someone work it out with you, ask in +[Matrix](https://matrix.to/#/#freenet-locutus:matrix.org). + +## What to put in a bug report + +You do not need to diagnose the problem. These are what make a report easy to act on: + +- What you were doing, what you expected, and what happened instead. +- Whether it happens every time or only sometimes. +- Your operating system, and how you installed Freenet. +- A screenshot, if it is something you can see. + +### The quick way to gather diagnostics + +If Freenet is installed on your machine, run this in a terminal: + +```bash +freenet service report +``` + +It asks you to describe the problem, gathers your version, operating system, recent log entries and +configuration, uploads them, and prints a short **report code** that looks like `X7K2M9`. Put that +code in your bug report and the maintainers can pull up everything they need. + +That upload includes recent log lines and your Freenet configuration file. If you would rather see +what is in it first, `freenet service report --local report.json` writes it to a file on your own +machine instead of uploading it. + +## Prefer to talk to a person? + +Our [Matrix room](https://matrix.to/#/#freenet-locutus:matrix.org) is where Freenet's developers and +users are. It is a good place for "is this even a bug?", for questions the FAQ does not answer, and +for anything you would rather not write up as a formal report. + +## Want to help fix things? + +A clear bug report is already a real contribution. If you want to go further, every Freenet project +takes pull requests and each has a `CONTRIBUTING.md` explaining how, starting with +[freenet-core](https://github.com/freenet/freenet-core/blob/main/CONTRIBUTING.md). The +[Build section](/build/) covers how Freenet works and how to write apps for it. diff --git a/hugo-site/content/quickstart/_index.md b/hugo-site/content/quickstart/_index.md index e8158c39..3e308233 100644 --- a/hugo-site/content/quickstart/_index.md +++ b/hugo-site/content/quickstart/_index.md @@ -44,7 +44,7 @@ Prefer the terminal? River has a full-featured CLI, `riverctl`. See the ## Troubleshooting If you run into problems, join our [Matrix chat](https://matrix.to/#/#freenet-locutus:matrix.org) -for help. +for help, or see [Report a Bug or Get Help](/community/support/) for where to file a report. **Invite didn't work?** If River opened but you're not in the room, try restarting Freenet (`freenet service restart`), then come back to this page and click the invite button again for a @@ -67,4 +67,4 @@ Need to remove Freenet? See the [uninstall guide](/uninstall/). - [User Manual](/build/manual/) - Learn how Freenet works - [Video Talks](/about/video-talks/) - Watch presentations about Freenet - [FAQ](/about/faq/) - Common questions and answers -- [Get Involved](/community/get-involved/) - Contribute to the project +- [Report a Bug or Get Help](/community/support/) - Where to send a bug report or feature idea diff --git a/hugo-site/themes/freenet/assets/css/freenet.css b/hugo-site/themes/freenet/assets/css/freenet.css index 5e8df7f9..c3be0d03 100644 --- a/hugo-site/themes/freenet/assets/css/freenet.css +++ b/hugo-site/themes/freenet/assets/css/freenet.css @@ -1107,6 +1107,43 @@ picture.app-screenshot img { } } +/* Bug-report route in the footer — the one support link present on every page, + so it has to read as a link rather than as a caption. */ +.footer-report { + text-align: center; + margin: 2rem auto 0; + padding: 0 1rem; + font-size: 0.9rem; +} + +.footer-report p { + margin: 0; +} + +.footer-report a { + color: #64748b; + text-decoration: underline; + text-decoration-color: rgba(100, 116, 139, 0.4); + text-underline-offset: 2px; +} + +.footer-report a:hover { + color: var(--color-primary); + text-decoration-color: var(--color-primary); +} + +@media (prefers-color-scheme: dark) { + .footer-report a { + color: #94a3b8; + text-decoration-color: rgba(148, 163, 184, 0.4); + } + + .footer-report a:hover { + color: #4da6ff; + text-decoration-color: #4da6ff; + } +} + /* Institutional statement in footer — quiet, just establishes 501(c)(3) status */ .footer-institutional { max-width: 720px; diff --git a/hugo-site/themes/freenet/layouts/partials/footer.html b/hugo-site/themes/freenet/layouts/partials/footer.html index 140bca16..0fadbb5a 100644 --- a/hugo-site/themes/freenet/layouts/partials/footer.html +++ b/hugo-site/themes/freenet/layouts/partials/footer.html @@ -1,3 +1,6 @@ + @@ -45,7 +45,7 @@

Get Involved

  • Run a peer: freenet.org/quickstart
  • Build: tutorial at freenet.org/resources/manual/tutorial, uses River as example
  • AI: dapp-builder skill for Claude
  • -
  • Matrix: #freenet:matrix.org
  • +
  • Matrix: #freenet-locutus:matrix.org
  • diff --git a/hugo-site/static/slides/common/questions.html b/hugo-site/static/slides/common/questions.html index 539cf014..61c215d8 100644 --- a/hugo-site/static/slides/common/questions.html +++ b/hugo-site/static/slides/common/questions.html @@ -12,7 +12,7 @@

    💬 - Matrix: #freenet:matrix.org + Matrix: #freenet-locutus:matrix.org

    𝕏