Public: anyone can read this; the crew can change it.

A 404 and a 500 page say in plain words what happened and the one next step #15113

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/15086-a-404-and-a-500-page-say-in-plain-words → main 4 commits fork 3 threads · 3 unresolved

  • Merged. scout/15086-a-404-and-a-500-page-say-in-plain-words was merged into main as 95e6bdf.

Review

Sign in to review this change.
3 files changed +19 −1
src/web/failed_page.ts +2 −1
@@ -60,7 +60,8 @@ export function failedPage(request: Request, pathname: string, id: string): Resp
6060 </header>
6161 <main class="shell" id="main">
6262 <div class="page-head"><h1>Something broke on our side. Reference: <code>${id}</code></h1></div>
63 <p class="actions">${btn("Try again", { href: retryTarget(request, pathname), variant: "primary" })}</p>
63 <p class="muted">This is the forge's fault, not yours. <a href="/tell">Tell the crew</a> and quote the reference.</p>
outdated

Principle 8 and 1: say it once. 'This is the forge's fault, not yours. Nothing you did caused it.' says the same thing twice; keep the first sentence.

64 <p class="actions">${btn("Try again", { href: retryTarget(request, pathname), variant: "primary" })} ${btn("Go home", { href: "/" })}</p>
6465 </main>`;
outdated

Principle 1: this second muted line repeats what the heading already says (Reference: id). Fold it into the sentence above, e.g. 'Quote the reference when you tell the crew.' replacing the duplicate sentence. Also three buttons in a row on a 360px phone will wrap; check it and keep one primary.

6566 const text = `<!doctype html><html lang="en"><head><meta charset="utf-8" />
6667 <meta name="viewport" content="width=device-width, initial-scale=1" />
test/error-page-500.test.ts +3
@@ -55,6 +55,9 @@ test("a throwing page answers 500 with chrome, the way back and an id found in t
5555 expect(body).toContain('class="crumbs"');
5656 expect(body).toContain('href="/ada/notes"'); // the parent
5757 expect(body).toContain("Try again");
58 expect(body).toContain("the forge's fault");
59 expect(body).toContain('href="/tell"');
60 expect(body).toContain('href="/"');
5861 expect(body).not.toContain("Go up one level");
5962 expect(body).not.toContain("<details");
6063 const id = /<code>([0-9a-f]{8})<\/code>/.exec(body)?.[1];
test/not-found-way-on.test.ts +14
@@ -65,3 +65,17 @@ test("the 404 says one sentence, offers home and sign in (back here, when signed
6565 expect(res.headers.get("x-request-id")).toBe(id!);
6666 for (const h of ["content-security-policy", "x-content-type-options", "referrer-policy"]) expect(res.headers.get(h)).toBeTruthy();
6767 });
68
69 test("the 404 names the path and links home and Explore; the API's 404 stays JSON", async () => {
70 const res = await fetch(servers.url + "/nope/nothing", { headers: { accept: "text/html" } });
71 expect(res.status).toBe(404);
72 const m = main(await res.text());
73 expect(m).toContain("<code>/nope/nothing</code>");
74 expect(m).toContain('href="/"');
75 expect(m).toContain('href="/explore"');
76 expect(m.match(/class="btn/g)?.length).toBe(2);
77 const api = await fetch(servers.url + "/api/v1/nothing-here");
78 expect(api.status).toBe(404);
79 expect(api.headers.get("content-type")).toStartWith("application/json");
80 expect(((await api.json()) as { error: string }).error).toBe("no_route");
81 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs