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

Calm pass: a pull reads as verdict, change and evidence #10377

Parked opened this in answer to
Closed without merging

torque/forge:torque/10300-calm-pass-a-pull-reads-as-verdict-change → main 7 commits fork 6 threads · 6 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
10 files changed +172 −29
docs/design/areas/pull.md +4
@@ -19,3 +19,7 @@ The pull page's cards (merge box, review, commits, slices, run-this-code) are `.
1919 ## The conflict resolver (#9713)
2020
2121 `/:owner/:name/pulls/:number/resolve`: each conflict block, the crew proposal and the empty states are a `<section>` with an `<h2>` over rows (no `card`), on the one background. The two sides lose their hairline box; the taps keep theirs (a control). The ours/theirs/both/Mine taps, the text box and `#crew-proposal` are unchanged. No new class; `test/conflicts.test.ts` holds it.
22
23 ## Verdict, then evidence (#10300)
24
25 The page reads in one order: the verdict (the check's dot and word, `#pull-check`), the decision (`#decide`, Ship), then the change. The check's line, holds, reviews and team verdicts sit in `<details id="evidence">` ("Checks and reviews", the `disclosure` of `src/web/ui.ts`), closed at rest. It opens by itself when the change is stopped, held or waiting on a review the repository requires, since that is what holds it, and for `?evidence=1`. The notes are gone: the Look block draws nothing until there is a picture, the composer no longer explains Markdown, and the decision says "Ready to ship." The pull's first-view budget fell from 133 to 89 words and 22 to 19 blocks. No new class; `test/pull-quiet.test.ts` holds it, with a pull for each reason the evidence opens.
outdated

Principle 8 (plain words, and the docs must be true): this says the budget fell from 133 to 85 words, but docs/design/attention-budget.json and docs/features/attention.md say 89. Fix the number here.

docs/design/attention-budget.json +6 −6
@@ -37,24 +37,24 @@
3737 },
3838 "pull": {
3939 "390": {
40 "words": 133,
41 "blocks": 22,
40 "words": 89,
41 "blocks": 19,
4242 "colours": 4
4343 },
4444 "1280": {
45 "words": 133,
46 "blocks": 22,
45 "words": 89,
46 "blocks": 19,
4747 "colours": 4
4848 }
4949 },
5050 "issue": {
5151 "390": {
52 "words": 76,
52 "words": 65,
5353 "blocks": 19,
5454 "colours": 2
5555 },
5656 "1280": {
57 "words": 76,
57 "words": 65,
5858 "blocks": 19,
5959 "colours": 2
6060 }
docs/features/attention.md +2 −2
@@ -24,8 +24,8 @@ reader sees on first view at 390 px and 1280 px: **words**, **text blocks** and
2424 | home | 95 / 20 / 2 | 95 / 20 / 2 |
2525 | repository | 116 / 18 / 2 | 116 / 18 / 2 |
2626 | app | 116 / 18 / 2 | 116 / 18 / 2 |
27 | pull | 133 / 22 / 4 | 133 / 22 / 4 |
28 | issue | 76 / 19 / 2 | 76 / 19 / 2 |
27 | pull | 89 / 19 / 4 | 89 / 19 / 4 |
28 | issue | 65 / 19 / 2 | 65 / 19 / 2 |
2929 | issues list | 32 / 8 / 2 | 32 / 8 / 2 |
3030 | pulls list | 31 / 7 / 1 | 31 / 7 / 1 |
3131 | runs | 46 / 8 / 1 | 46 / 8 / 1 |
src/web/pages/looks.ts +2 −6
@@ -153,12 +153,8 @@ export function lookCard(
153153 ${body}
154154 </section>`;
155155 if (taken.length === 0 && attached.length === 0) {
156 if (pull.state !== "open" || pull.mergedAt !== null) return html``;
157 return block(
158 html`<p class="muted small">
159 No picture yet. One is taken when the preview comes up green.
160 </p>`,
161 );
156 // Nothing to show is no block: a heading over a note is a tap with nothing behind it.
157 return html``;
162158 }
163159 // Home first, then the rest in the order the manifest is likeliest to
164160 // read them — alphabetically, since the row order says nothing about it.
src/web/pages/thread.ts +6 −8
@@ -630,17 +630,15 @@ export function composer(ctx: Ctx, o: ComposerOptions): Html {
630630 ? null
631631 : html`<p class="muted small crew-note">${o.crewNote}</p>`}
632632 <div class="form-actions">
633 <span class="muted small"
634 >${tell
635 ? html`${tell.from && !tell.ask
633 ${tell
634 ? html`<span class="muted small"
635 >${tell.from && !tell.ask
636636 ? html`From <code>${tell.from}</code>. `
637637 : null}${tell.page
638638 ? html`From <code>${tell.page}</code>. `
639 : null}Enter sends.`
640 : html`${icon("file")} Markdown is supported —
641 <code>**bold**</code>, <code>[link](url)</code>,
642 <code>&gt; quote</code>.`}</span
643 >
639 : null}Enter sends.</span
640 >`
outdated

Principle 1: this leaves an empty span when there is no tell. Render the span only when it has content.

641 : null}
644642 <span class="spacer"></span>
645643 ${reasons} ${closeButton}
646644 ${tell
src/web/studio/change.ts +21 −5
@@ -60,6 +60,7 @@ import {
6060 tlEvent,
6161 userLink,
6262 verdictBadge,
63 disclosure,
6364 type Tone,
6465 } from "../ui.ts";
6566 import { previewBlock } from "../pages/apps.ts";
@@ -536,10 +537,10 @@ async function changeConversation(
536537 who: pull.authorName,
537538 says:
538539 word === "look"
539 ? "The check is green. Look at the preview, then ship it or say what is off."
540 : record === undefined
541 ? "Nothing here waits on a check to ship. Read it, then ship it or say what is off."
542 : "This app does not wait on the check to ship. Look at the preview, then ship it or say what is off.",
540 ? "The check is green. Ship it or say what is off."
541 : repo.requireChecks
outdated

Principle 8: "Ready to ship." loses the plain reason there is no check to wait on. Keep a short clause for the no-check case.

542 ? "Ready to ship."
543 : "No check is set. Ready to ship.",
543544 short: word === "look" ? "the check is green" : "ready to ship",
544545 consequence: KIND_TIER.look,
545546 waiting: waitingFor({
@@ -729,6 +730,20 @@ async function changeConversation(
729730 });
730731 spent.reviews += performance.now() - reviewsAt;
731732
733 // The evidence behind the verdict — the check's line, holds, reviews —
734 // opens in place; a failing, held or review-waiting change opens it,
735 // since that is what holds it. The verdict and the decision above it stay on the page.
736 const evidenceBody = html`${when(runLine, (l) => l)} ${gate}`;
outdated

The evidence opens only for stopped or held. A pull with a review requested or waiting stays closed, and the summary carries no state. Open it for a pending review too, or put the state in the summary.

737 const evidence = disclosure("Checks and reviews", evidenceBody, {
738 id: "evidence",
739 small: true,
740 open:

This open condition (stopped, held, !reviewed) is behaviour this pull adds, and no test covers it. Add tests with fixtures for each case, asserting the details carries open, so they fail if the condition is removed. This includes the review gate, which the builder said was skipped.

741 word === "stopped" ||
742 held ||
743 !reviewed ||
744 ctx.url.searchParams.has("evidence"),
745 });
746
732747 // From here on nothing is read: `render` only builds the page.
733748 const body = html`${pageHead.top}
734749 ${when(siblings.length > 0, () =>
@@ -739,7 +754,8 @@ async function changeConversation(
739754 </p>`,
740755 )}
741756 <div id="pull-check">${checkLine}</div>
742 ${when(runLine, (l) => l)} ${gate} ${decisionSection}
757 ${decisionSection}
758 ${evidence}
743759 ${when(visionPreview, (v) => visionPreviewCard(v))}
744760 ${look}
745761 <div class="split">
src/web/ui.ts +3 −1
@@ -937,13 +937,15 @@ export interface DisclosureOptions {
937937 label?: string;
938938 /** Further classes for the `<details>` (a spacing utility such as `mt`). */
939939 extra?: string;
940 /** Render it open. */
941 open?: boolean;
940942 /** The `<details>`'s id, for a script or a link that finds it. */
941943 id?: string;
942944 }
943945
944946 /** What a person sometimes needs, closed until asked for: a quiet chevron summary over its body. */
945947 export function disclosure(summary: Html | string, body: Html | string, o: DisclosureOptions = {}): Html {
946 return html`<details${o.id ? html` id="${o.id}"` : null} class="disclosure${o.extra ? ` ${o.extra}` : ""}">
948 return html`<details${o.id ? html` id="${o.id}"` : null}${o.open ? raw(" open") : null} class="disclosure${o.extra ? ` ${o.extra}` : ""}">
947949 <summary${o.small ? html` class="muted small"` : null}${o.label ? html` aria-label="${o.label}"` : null}>${summary}</summary>
948950 ${body}
949951 </details>`;
test/pull-evidence-opens.test.ts added +106
@@ -0,0 +1,106 @@
1 /**
2 * A pull's evidence (checks and reviews) opens by itself when the pull is stopped, held or waiting on a review (#10300).
3 * Its own forge, apart from test/pull-quiet.test.ts: the palette lists every repository an admin can see, so the
4 * repositories seeded here would grow the pages whose bytes that file holds.
5 */
6 import { afterAll, beforeAll, expect, test } from "bun:test";
7 import { mkdtemp, rm } from "node:fs/promises";
8 import { tmpdir } from "node:os";
9 import { join } from "node:path";
10 import { createApp, type App } from "../src/app.ts";
11 import { holdPull } from "../src/actions/holds.ts";
12 import { openPull } from "../src/actions/pulls.ts";
13 import { commitToBranch, createRepo } from "../src/actions/repos.ts";
14 import { updateRepoSettings, type Repo } from "../src/core/repos.ts";
15 import { claimRun, createRun, finishRun } from "../src/core/runs.ts";
16 import { createSession } from "../src/core/sessions.ts";
17 import { createUser } from "../src/core/users.ts";
18 import { serve, type Servers } from "../src/http/server.ts";
19 import { quietLogs } from "./helpers/globals.ts";
20
21 quietLogs();
22
23 let dataDir: string;
24 let app: App;
25 let servers: Servers;
26 let cookie = "";
27 // One pull per reason the evidence opens by itself, and one that holds nothing to tell them apart from.
28 const paths = { quiet: "", stopped: "", held: "", unreviewed: "" };
29 const cells = process.env["FORGE_CELLS"];
30
31 beforeAll(async () => {
32 process.env["FORGE_CELLS"] = "off";
33 dataDir = await mkdtemp(join(tmpdir(), "forge-pull-evidence-"));
34 app = createApp({ dataDir, port: 0 });
35 servers = await serve(app);
36 const made = await createUser(app.db, {
37 origin: "seed",
38 trusted: true,
39 username: "alice",
40 email: "[email protected]",
41 password: "a-good-passphrase",
42 adminIfFirst: true,
43 });
44 if (!made.ok) throw new Error(String(made.error));
45 const user = made.value;
46 cookie = `forge_session=${createSession(app.db, user.id).token}`;
47
48 const repoNamed = async (name: string): Promise<Repo> => {
49 const repo = await createRepo(app, user, { name, visibility: "public" });
50 if (!repo.ok) throw new Error(String(repo.error));
51 const init = await commitToBranch(app, user, repo.value, { message: "init", files: [{ path: "forge.json", content: "{}" }] });
52 if (!init.ok) throw new Error(JSON.stringify(init.error));
53 return repo.value;
54 };
55 const pullOn = async (repo: Repo, branch: string) => {
56 const done = await commitToBranch(app, user, repo, { branch, message: branch, files: [{ path: `${branch}.txt`, content: branch }] });
57 if (!done.ok) throw new Error(JSON.stringify(done.error));
58 const opened = await openPull(app, user, repo, { title: branch, body: branch, baseBranch: "main", headBranch: branch });
59 if (!opened.ok) throw new Error(JSON.stringify(opened.error));
60 return opened.value;
61 };
62
63 const busy = await repoNamed("busy");
64 // Quiet: open, no check, no hold, no review asked for.
65 paths.quiet = `/alice/busy/pulls/${(await pullOn(busy, "quiet")).number}`;
66 // Stopped: the head's check ran and failed.
67 const failed = await pullOn(busy, "failing");
68 const run = createRun(app.db, { repoId: busy.id, kind: "check", issueId: failed.id, env: `pull-${failed.number}`, commitOid: failed.headOid, reason: "pull" });
69 claimRun(app.db, run.id);
70 finishRun(app.db, run.id, { state: "failed", summary: "failed" });
71 paths.stopped = `/alice/busy/pulls/${failed.number}`;
72 // Held: a writer holds it, with a line saying why.
73 const heldPull = await pullOn(busy, "holding");
74 const hold = holdPull(app, user, busy, heldPull, "waiting on the schema");
75 if (!hold.ok) throw new Error(String(hold.error));
76 paths.held = `/alice/busy/pulls/${heldPull.number}`;
77 // Unreviewed: a repository that requires a review, and none given.
78 const gated = await repoNamed("gated");
79 const strict = updateRepoSettings(app.db, gated, { ...gated, requireReview: true });
80 paths.unreviewed = `/alice/gated/pulls/${(await pullOn(strict, "waiting")).number}`;
81 });
82
83 afterAll(async () => {
84 await servers.stop();
85 app.close();
86 if (cells === undefined) delete process.env["FORGE_CELLS"];
87 else process.env["FORGE_CELLS"] = cells;
88 await rm(dataDir, { recursive: true, force: true });
89 });
90
91 const get = async (path: string) => (await fetch(`${servers.url}${path}`, { headers: { cookie } })).text();
92 const evidenceTag = (text: string) => text.match(/<details id="evidence"[^>]*>/)?.[0] ?? "";
93
94 test("the evidence opens by itself on a stopped, held or review-waiting pull, and stays closed on a quiet one (#10300)", async () => {
95 const quiet = evidenceTag(await get(paths.quiet));
96 expect(quiet).not.toBe("");
97 expect(quiet).not.toContain(" open");
98 for (const why of ["stopped", "held", "unreviewed"] as const) {
99 const tag = evidenceTag(await get(paths[why]));
100 expect(tag, why).not.toBe("");
101 expect(tag, why).toContain(" open");
102 }
103 // Each opens for its own reason: the stopped pull says stopped, the held one names its hold.
104 expect(await get(paths.stopped)).toMatch(/data-pull-word>stopped</);
105 expect(await get(paths.held)).toContain("waiting on the schema");
106 });
test/pull-quiet.test.ts +21
@@ -102,3 +102,24 @@ test("every action the pull page offered is still on it", async () => {
102102 const text = await get(`/alice/r/pulls/${number}`);
103103 for (const needle of ["/pulls/" + number + "/comments", "Close pull request", "Pulls", "Issues", "Files"]) expect(text).toContain(needle);
104104 });
105
106 test("a pull reads as verdict, then evidence in place, with no notes (#10300)", async () => {
107 const text = await get(`/alice/r/pulls/${number}`);
108 const at = (s: string) => text.indexOf(s);
109 // The verdict and the decision come before the evidence.
110 expect(at('id="pull-check"')).toBeGreaterThan(-1);
111 expect(at('id="decide"')).toBeGreaterThan(at('id="pull-check"'));
112 expect(at('id="evidence"')).toBeGreaterThan(at('id="decide"'));
113 // The evidence is a closed disclosure on a pull that holds nothing, and holds the checks line.
114 const ev = text.match(/<details id="evidence"[^>]*>[\s\S]*?<\/details>/)?.[0] ?? "";
115 expect(ev).not.toMatch(/^<details[^>]* open/);
116 expect(ev).toContain("Checks and reviews");
117 expect(ev).toContain('id="live-checks"');
118 // An open pull holding nothing opens it with ?evidence, with no script.
119 expect(await get(`/alice/r/pulls/${number}?evidence=1`)).toMatch(/<details id="evidence" open/);
120 // No notes: a heading over "no picture yet", the Markdown hint.
121 expect(text).not.toContain("No picture yet");
122 expect(text).not.toContain("Markdown is supported");
123 // No empty span where the composer has no tell to say.
124 expect(text).not.toMatch(/<span class="muted small">\s*<\/span>/);
125 });
test/studio.test.ts +1 −1
@@ -790,7 +790,7 @@ describe("the studio", () => {
790790 expect(change).not.toContain("diff-table");
791791 // No app: no preview and no look, and the decision does not say "app".
792792 expect(change).not.toContain("<h2>Preview</h2>");
793 expect(change).toContain("Nothing here waits on a check to ship.");
793 expect(change).toContain("No check is set. Ready to ship.");
794794
795795 const files = await (
796796 await get(`/alice/plainrepo/pulls/${pull.number}/files`)

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs