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

Merged opened this

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

Merged

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.

Notes

shipped production is serving it deploy 404563e

opened this

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 required reason, and /admin/limits already shows it. I added no code there.
  • Added: capacity settings (CAPACITY in src/core/capacity.ts) had only a help paragraph, so each of the 18 entries now has a required reason field with a one-sentence reason. src/actions/capacity.ts passes it through, and src/web/pages/capacity.ts shows it above the help text.
  • Test: test/settings-reasons.test.ts checks that every LIMITS and CAPACITY entry has a non-empty one-sentence reason. It also checks that the capacity page renders each reason.

Left out:

  • children.originEgress has 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 than limits.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.

Closes #14071

7 earlier comments · 2 events
commented

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 required reason, and /admin/limits already shows it. I added no code there.
  • Added: capacity settings (CAPACITY in src/core/capacity.ts) had only a help paragraph, so each of the 18 entries now has a required reason field with a one-sentence reason. src/actions/capacity.ts passes it through, and src/web/pages/capacity.ts shows it above the help text.
  • Test: test/settings-reasons.test.ts checks that every LIMITS and CAPACITY entry has a non-empty one-sentence reason. It also checks that the capacity page renders each reason.

Left out:

  • children.originEgress has 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 than limits.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.

commented

<!-- 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
commented

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 required reason. It is carried through src/actions/capacity.ts to the page in src/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.ts shows the reason as a muted line under each row. That makes rows taller, so test/tui-capacity.test.ts now boots a 60-row terminal instead of 40 so the Self-swap row stays on screen.
  • Docs: docs/features/capacity.md has a short "Why each setting is there" section.
  • Test: test/settings-reasons.test.ts checks every LIMITS and CAPACITY reason, that the page renders each capacity reason, and that the terminal screen shows its reason.

Left out

  • children.originEgress has 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.reason in the screen source; it doesn't render the row.
  • src/web/pages/config.ts is 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.

commented

<!-- 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
commented

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 — before the latest push

Changes requested. Two things to fix first.

  1. 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.
  2. 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 example cells.servingCores starts "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.

commented

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's note: r.reason replaced 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 .why component (why() from src/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.md notes where the capacity page puts .why.
    • Help text: I dropped the "Why:" opening from the cells.servingCores help, since the reason now says it.
  • 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.

commented

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.servingCores help text starts with "Why:". An earlier commit on this pull moved that reason into its own reason field, so the help text no longer starts that way. The test was wrong, not the code, so it now asserts that reason is 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 --noEmit is clean. The gate only noted one long comment line in src/web/pages/capacity.ts and 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.

Approved

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:

  1. 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).
  2. 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.
commented

Left #14071 open: 1 unticked item remain (the settings page shows it under the label).

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs