Public: anyone can read this; the crew can change it.
Calm pass: a pull reads as verdict, change and evidence #10377
torque/forge:torque/10300-calm-pass-a-pull-reads-as-verdict-change → main 7 commits fork 6 threads · 6 unresolved
docs/design/areas/pull.md +4
| @@ -19,3 +19,7 @@ The pull page's cards (merge box, review, commits, slices, run-this-code) are `. | ||
| 19 | 19 | ## The conflict resolver (#9713) |
| 20 | 20 | |
| 21 | 21 | `/: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. | |
docs/design/attention-budget.json +6 −6
| @@ -37,24 +37,24 @@ | ||
| 37 | 37 | }, |
| 38 | 38 | "pull": { |
| 39 | 39 | "390": { |
| 40 | "words": 133, | |
| 41 | "blocks": 22, | |
| 40 | "words": 89, | |
| 41 | "blocks": 19, | |
| 42 | 42 | "colours": 4 |
| 43 | 43 | }, |
| 44 | 44 | "1280": { |
| 45 | "words": 133, | |
| 46 | "blocks": 22, | |
| 45 | "words": 89, | |
| 46 | "blocks": 19, | |
| 47 | 47 | "colours": 4 |
| 48 | 48 | } |
| 49 | 49 | }, |
| 50 | 50 | "issue": { |
| 51 | 51 | "390": { |
| 52 | "words": 76, | |
| 52 | "words": 65, | |
| 53 | 53 | "blocks": 19, |
| 54 | 54 | "colours": 2 |
| 55 | 55 | }, |
| 56 | 56 | "1280": { |
| 57 | "words": 76, | |
| 57 | "words": 65, | |
| 58 | 58 | "blocks": 19, |
| 59 | 59 | "colours": 2 |
| 60 | 60 | } |
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 | ||
| 24 | 24 | | home | 95 / 20 / 2 | 95 / 20 / 2 | |
| 25 | 25 | | repository | 116 / 18 / 2 | 116 / 18 / 2 | |
| 26 | 26 | | 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 | | |
| 29 | 29 | | issues list | 32 / 8 / 2 | 32 / 8 / 2 | |
| 30 | 30 | | pulls list | 31 / 7 / 1 | 31 / 7 / 1 | |
| 31 | 31 | | runs | 46 / 8 / 1 | 46 / 8 / 1 | |
src/web/pages/looks.ts +2 −6
| @@ -153,12 +153,8 @@ export function lookCard( | ||
| 153 | 153 | ${body} |
| 154 | 154 | </section>`; |
| 155 | 155 | 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``; | |
| 162 | 158 | } |
| 163 | 159 | // Home first, then the rest in the order the manifest is likeliest to |
| 164 | 160 | // 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 { | ||
| 630 | 630 | ? null |
| 631 | 631 | : html`<p class="muted small crew-note">${o.crewNote}</p>`} |
| 632 | 632 | <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 | |
| 636 | 636 | ? html`From <code>${tell.from}</code>. ` |
| 637 | 637 | : null}${tell.page |
| 638 | 638 | ? 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>> 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} | |
| 644 | 642 | <span class="spacer"></span> |
| 645 | 643 | ${reasons} ${closeButton} |
| 646 | 644 | ${tell |
src/web/studio/change.ts +21 −5
| @@ -60,6 +60,7 @@ import { | ||
| 60 | 60 | tlEvent, |
| 61 | 61 | userLink, |
| 62 | 62 | verdictBadge, |
| 63 | disclosure, | |
| 63 | 64 | type Tone, |
| 64 | 65 | } from "../ui.ts"; |
| 65 | 66 | import { previewBlock } from "../pages/apps.ts"; |
| @@ -536,10 +537,10 @@ async function changeConversation( | ||
| 536 | 537 | who: pull.authorName, |
| 537 | 538 | says: |
| 538 | 539 | 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.", | |
| 543 | 544 | short: word === "look" ? "the check is green" : "ready to ship", |
| 544 | 545 | consequence: KIND_TIER.look, |
| 545 | 546 | waiting: waitingFor({ |
| @@ -729,6 +730,20 @@ async function changeConversation( | ||
| 729 | 730 | }); |
| 730 | 731 | spent.reviews += performance.now() - reviewsAt; |
| 731 | 732 | |
| 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 | ||
| 732 | 747 | // From here on nothing is read: `render` only builds the page. |
| 733 | 748 | const body = html`${pageHead.top} |
| 734 | 749 | ${when(siblings.length > 0, () => |
| @@ -739,7 +754,8 @@ async function changeConversation( | ||
| 739 | 754 | </p>`, |
| 740 | 755 | )} |
| 741 | 756 | <div id="pull-check">${checkLine}</div> |
| 742 | ${when(runLine, (l) => l)} ${gate} ${decisionSection} | |
| 757 | ${decisionSection} | |
| 758 | ${evidence} | |
| 743 | 759 | ${when(visionPreview, (v) => visionPreviewCard(v))} |
| 744 | 760 | ${look} |
| 745 | 761 | <div class="split"> |
src/web/ui.ts +3 −1
| @@ -937,13 +937,15 @@ export interface DisclosureOptions { | ||
| 937 | 937 | label?: string; |
| 938 | 938 | /** Further classes for the `<details>` (a spacing utility such as `mt`). */ |
| 939 | 939 | extra?: string; |
| 940 | /** Render it open. */ | |
| 941 | open?: boolean; | |
| 940 | 942 | /** The `<details>`'s id, for a script or a link that finds it. */ |
| 941 | 943 | id?: string; |
| 942 | 944 | } |
| 943 | 945 | |
| 944 | 946 | /** What a person sometimes needs, closed until asked for: a quiet chevron summary over its body. */ |
| 945 | 947 | 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}` : ""}"> | |
| 947 | 949 | <summary${o.small ? html` class="muted small"` : null}${o.label ? html` aria-label="${o.label}"` : null}>${summary}</summary> |
| 948 | 950 | ${body} |
| 949 | 951 | </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 () => { | ||
| 102 | 102 | const text = await get(`/alice/r/pulls/${number}`); |
| 103 | 103 | for (const needle of ["/pulls/" + number + "/comments", "Close pull request", "Pulls", "Issues", "Files"]) expect(text).toContain(needle); |
| 104 | 104 | }); |
| 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", () => { | ||
| 790 | 790 | expect(change).not.toContain("diff-table"); |
| 791 | 791 | // No app: no preview and no look, and the decision does not say "app". |
| 792 | 792 | 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."); | |
| 794 | 794 | |
| 795 | 795 | const files = await ( |
| 796 | 796 | await get(`/alice/plainrepo/pulls/${pull.number}/files`) |
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.