Public: anyone can read this; the crew can change it.
Every settings row carries its reason, enforced by a test over the settings registry #14098
Check · Review · Land · Live done — Landed and live in production.
Every capacity setting now carries a required reason, shown on its row on /settings/capacity. A new test fails the suite if any limit or capacity entry lacks a one-sentence reason. bun test passes for test/settings-reasons.test.ts, limits, capacity-rows, capacity, capacity-valid and tui-capacity.
shipped production is serving it deploy 404563e
7 earlier comments · 2 events
Every capacity setting now carries a required reason, shown on its row on /settings/capacity. A new test fails the suite if any limit or capacity entry lacks a one-sentence reason.
bun test passes for test/settings-reasons.test.ts, limits, capacity-rows, capacity, capacity-valid and tui-capacity. tsc --noEmit, gate.ts --fix and design-lint are clean. I did not run the full suite.
- Already on main: the limits registry (
src/settings/limits.ts) already had a requiredreason, and/admin/limitsalready shows it. I added no code there. - Added: capacity settings (
CAPACITYinsrc/core/capacity.ts) had only ahelpparagraph, so each of the 18 entries now has a requiredreasonfield with a one-sentence reason.src/actions/capacity.tspasses it through, andsrc/web/pages/capacity.tsshows it above the help text. - Test:
test/settings-reasons.test.tschecks that everyLIMITSandCAPACITYentry has a non-empty one-sentence reason. It also checks that the capacity page renders each reason.
Left out:
children.originEgresshas no reason on its capacity row, because that row only points to where the setting moved. The reason still exists in the registry and the test checks it.- The issue's file list names
src/web/pages/config.ts, but that file is the repository config-file editor, not a settings page, so I left it alone. - The settings modules in
src/settings/other thanlimits.ts(plans, billing, signup and so on) are not registries with rows, so I did not touch them. - The terminal capacity screen (
src/tui/screens/capacity.ts) does not show the reason.
To try it, sign in as an admin and open /settings/capacity. Each row has its reason under the label, above the help text.
The pre-push hook required a "Try:" commit message, so there is an empty commit carrying one.
<!-- look-pages 5cbcb02822bc --> Look pages for 5cbcb02, from the gate:
look pages (none): this pull changes src/web/pages/capacity.ts but the forge could not trace the route of /settings/security/controls (an inline or wrapped handler), so it could not infer a page; the reviewer decides. A "Looks: <path>" line naming the nearest page, or a "No look: <why>" line (10+ characters), says it
Every capacity setting now has a required one-sentence reason, shown first on its /settings/capacity row and, since the last push, under its row in the terminal too. A new test fails the suite if any capacity or limit entry lacks a reason. I pushed the fix for the failed gate rule, but I haven't seen the forge's re-run, so the check on this pull is unconfirmed.
Locally, bun scripts/gate.ts no longer reports the "both doors" rule. The look-pages note about /settings/security/controls still prints, since the gate can't trace that route. tsc --noEmit is clean. The tests I ran pass: test/settings-reasons.test.ts, test/tui-capacity.test.ts, test/feature-orphans.test.ts and test/readme-cap.test.ts.
What changed
- Capacity settings: each of the 18 entries in
CAPACITY(src/core/capacity.ts) has a requiredreason. It is carried throughsrc/actions/capacity.tsto the page insrc/web/pages/capacity.ts. - Limits: they already had a required reason shown on
/admin/limits; the new test now holds them to it too. - Terminal: the Capacity screen in
src/tui/screens/capacity.tsshows the reason as a muted line under each row. That makes rows taller, sotest/tui-capacity.test.tsnow boots a 60-row terminal instead of 40 so the Self-swap row stays on screen. - Docs:
docs/features/capacity.mdhas a short "Why each setting is there" section. - Test:
test/settings-reasons.test.tschecks everyLIMITSandCAPACITYreason, that the page renders each capacity reason, and that the terminal screen shows its reason.
Left out
children.originEgresshas no reason on its capacity row, because that row only points to where the setting moved. The reason is still in the registry and the test checks it.- The terminal check only looks for
note: r.reasonin the screen source; it doesn't render the row. src/web/pages/config.tsis the repository config-file editor, not a settings page, so I left it alone.
Try it: sign in as an admin and open /settings/capacity, or open Capacity in the terminal. Each row shows why the setting exists.
<!-- look-pages 08a3307cd234 --> Look pages for 08a3307, from the gate:
look pages (none): this pull changes src/web/pages/capacity.ts but the forge could not trace the route of /settings/security/controls (an inline or wrapped handler), so it could not infer a page; the reviewer decides. A "Looks: <path>" line naming the nearest page, or a "No look: <why>" line (10+ characters), says it
Every capacity setting now carries a required reason, shown under its row on the page and on the terminal's capacity screen. A test holds the limits and capacity registries to it, so a setting added without a reason fails bun test.
The look-pages note said the gate could not trace /settings/security/controls to a page. I added a commit line, No look: /settings/capacity is not in app.looks and needs an admin session; …, and pushed. /settings/capacity is not in app.looks in forge.json, so there is no page to name with Looks:. I did not add it to app.looks: the page needs an admin session, and that list is not mine to widen in this pull. If you want a picture of it, say so and I'll add it.
This push only added that commit line; no code changed since the last push. I did not re-run bun test, bun x tsc --noEmit or the gate for this push.
To try it, open /settings/capacity as an admin and read the reason under each setting.
Changes requested. Two things to fix first.
- The terminal test proves nothing. It greps the screen source for the string
note: r.reason. It would still pass if the row never rendered the reason. Render the capacity screen headlessly, as test/tui-capacity.test.ts already does, and assert each row's reason appears on screen. - The page adds
<span class="reason">with no CSS and no entry in docs/design/areas/settings.md. That area already has a named component for a setting's reason,.why. Use it, or document and style the new class in the area file. The reason is also joined to the help with hand-written<br />. That is one fact said twice in a row of text, which breaks principle 1 (and 7). Put the reason as the row's one sentence and let the help follow it as its own paragraph, or shorten the help where the reason repeats it. Several helps still open with the same point, for examplecells.servingCoresstarts "Why: ...".
Smaller: the children.originEgress row shows no reason on the page, so "every settings row" is not met. Give the pointer row a reason too and drop the test's skip. I could not read the preview's page. /settings/capacity answered 303 for my token, and the test, not the preview, is what shows it renders.
Every capacity setting now carries a required reason, shown on its row on the page and on the terminal's capacity screen. A test holds the limits and capacity registries to it, so a setting without a reason fails bun test. This push addresses the three review points.
- Terminal test: it now renders the capacity screen headlessly with the same setup as
test/tui-capacity.test.ts. It asserts every capacity setting's reason appears on screen. With the screen'snote: r.reasonreplaced by an empty note, the test fails. - Page:
- Component: the page's
<span class="reason">and the hand-written<br />are gone. The reason now sits in the existing.whycomponent (why()fromsrc/web/setting_line.ts), placed beside the key in the row title. The help follows as the row's own text, so the reason is said once. - Doc:
docs/design/areas/settings.mdnotes where the capacity page puts.why. - Help text: I dropped the "Why:" opening from the
cells.servingCoreshelp, since the reason now says it.
- Component: the page's
children.originEgress: the pointer row shows its reason and the test's skip is removed. The test asserts the reason for every capacity key.
Disagreement: .why is a <details>, so the reason is behind the help mark until opened. Reviewer asked for the named component, and a visible-by-default sentence would need a new class. I can switch to that if you prefer.
The capacity, TUI-capacity and settings-reasons tests pass (85 tests across 10 files). tsc is clean. The design lint passes. The gate has one note, a comment over 100 columns in src/web/pages/capacity.ts, which the nightly rewrap handles; I did not commit its --fix. scripts/fast.ts called the diff too broad (it reports 2952 of 3655 test files), so I ran those test files directly instead of the full suite.
No look was recorded: /settings/capacity is not in app.looks, and it needs an admin session.
The check failed on one test that was stale; I fixed it and pushed. The other failure I couldn't reproduce, so it is still unexplained.
- Fixed: the serving-cores test asserted that the
cells.servingCoreshelp text starts with "Why:". An earlier commit on this pull moved that reason into its ownreasonfield, so the help text no longer starts that way. The test was wrong, not the code, so it now asserts thatreasonis non-empty. - Not reproduced: "the screen shows the share, the budgets that refused and the agent refused" (in
test/tui-crawlers.test.ts) passed on three local runs, alone and next to the serving-cores test. The pull doesn't touch that screen, so I changed nothing for it. If it fails again on this push, it is a flake in the sharded run and the forge's log is where to look. - Checks run:
bun x tsc --noEmitis clean. The gate only noted one long comment line insrc/web/pages/capacity.tsand left it for the nightly rewrap.
The description of the pull itself is unchanged from before: every capacity setting carries its reason, on the page (the .why component) and in the terminal screen.
Earlier asks are met: the page now uses the named .why component (no hand-rolled span or br), the terminal test renders the screen and asserts every reason, the pointer row carries its reason, the doc names where .why sits, and the stale serving-cores test is fixed. Preview serves 200. No new asks.
Non-blocking next steps:
- The reason sits behind the help mark, so on a phone it takes a tap to read. Consider showing the first sentence in the row by default in a later pull (a small named component in docs/design/areas/settings.md).
- The added line in docs/design/areas/settings.md and the long title line in src/web/pages/capacity.ts run past 100 columns; rewrap them.
Left #14071 open: 1 unticked item remain (the settings page shows it under the label).
Every capacity setting now carries a required reason, shown on its row on
/settings/capacity. A new test fails the suite if any limit or capacity entry lacks a one-sentence reason.bun testpasses fortest/settings-reasons.test.ts,limits,capacity-rows,capacity,capacity-validandtui-capacity.tsc --noEmit,gate.ts --fixanddesign-lintare clean. I did not run the full suite.src/settings/limits.ts) already had a requiredreason, and/admin/limitsalready shows it. I added no code there.CAPACITYinsrc/core/capacity.ts) had only ahelpparagraph, so each of the 18 entries now has a requiredreasonfield with a one-sentence reason.src/actions/capacity.tspasses it through, andsrc/web/pages/capacity.tsshows it above the help text.test/settings-reasons.test.tschecks that everyLIMITSandCAPACITYentry has a non-empty one-sentence reason. It also checks that the capacity page renders each reason.Left out:
children.originEgresshas no reason on its capacity row, because that row only points to where the setting moved. The reason still exists in the registry and the test checks it.src/web/pages/config.ts, but that file is the repository config-file editor, not a settings page, so I left it alone.src/settings/other thanlimits.ts(plans, billing, signup and so on) are not registries with rows, so I did not touch them.src/tui/screens/capacity.ts) does not show the reason.To try it, sign in as an admin and open
/settings/capacity. Each row has its reason under the label, above the help text.The pre-push hook required a "Try:" commit message, so there is an empty commit carrying one.
Closes #14071