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

/changelog opens on the newest wave with its milestone distance as 'N of M done' above the entries #14530

Merged opened this

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

Merged

torque/forge:torque/14502-changelog-opens-on-the-newest-wave-with → main 7 commits fork 5 threads · 5 unresolved

  • Merged. torque/14502-changelog-opens-on-the-newest-wave-with was merged into main as 2f48880.

Review

Sign in to review this change.
8 files changed +168 −5
docs/features/changelog.md +4
@@ -97,3 +97,7 @@ When no pull has landed, `/changelog` shows one sentence in place of the "Live:"
9797 ## A closed chapter's wave
9898
9999 When a chapter closes (for example one named `v1.1.0`), its wave is told on `/changelog`, in the JSON (`waves[].sentence`, `waves[].links`) and on the terminal's Changelog screen. The sentence is the chapter row's meta; a pull the wave names that the chapter's landed rows do not already list gets a row of its own, and on the terminal each such line carries its pull number, so Enter opens it. The page's tag holds the default branch tip of each repository, one ref read, and wave files are read only when the tag misses (`waveTips`, `withWaves` in `src/release/chapter_waves.ts`). To try it, close a chapter, then open `/changelog`. Tested in `test/changelog-chapters.test.ts`.
100
101 ## The newest wave's milestone (#14502)
102
103 `/changelog` says, beside the newest wave's sentence, how far the widest milestone that wave moved has come: "The milestone: <name>: N of M done", counted by the plan the milestone page reads (`src/web/pages/wave_standing.ts`, `withStanding`). A wave that moved no milestone says nothing. The terminal's Changelog screen (`src/tui/screens/changelog.ts`) shows the same line under the wave's sentence, from the same function. The page's tag holds the last change to any issue of a repository with a chapter, so closing an issue refreshes the count rather than serving a 304. Tested in `test/changelog-wave-standing.test.ts` and, for the terminal line, `test/tui-changelog.test.ts`.
outdated

Says the page shows 'The milestone: <name>: N of M done'; the page shows '<name>: N of M done'. Align.

src/release/chapter_groups.ts +1 −1
@@ -30,7 +30,7 @@ export type Group =
3030 | { readonly kind: "between"; readonly landings: readonly Landing[] };
3131
3232 /** Newest chapter first: the open one, then by closing time, later position breaking a tie. */
33 function newest(a: ChapterEntry, b: ChapterEntry): number {
33 export function newest(a: ChapterEntry, b: ChapterEntry): number {
3434 const at = (e: ChapterEntry): number => (e.chapter.closedAt === null ? Infinity : Date.parse(e.chapter.closedAt));
3535 return at(b) === at(a) ? b.chapter.position - a.chapter.position : at(b) < at(a) ? -1 : 1;
3636 }
src/release/chapter_waves.ts +5
@@ -21,6 +21,11 @@ export interface ChapterWave {
2121 * number).
2222 */
2323 readonly pulls: readonly { readonly title: string; readonly url: string; readonly number: number }[];
outdated

This block sits between the pulls doc comment and its field, so 'Each pull the wave names' now documents milestone. Move it below pulls.

24 /**
25 * The widest milestone the wave moved, as the milestone page counts it now; set only on the
26 * newest wave (`web/pages/wave_standing.ts`), never kept with the file.
27 */
28 readonly milestone?: { readonly title: string; readonly done: number; readonly total: number };
2429 }
2530
2631 /**
src/tui/screens/changelog.ts +5 −1
@@ -18,6 +18,8 @@ import { repoDir } from "../../git/repos.ts";
1818 import { forgeChangelog, type ReleaseEntry } from "../../release/changelog.ts";
1919 import { readLandings, type Landing } from "../../release/landings.ts";
2020 import { nearMilestones, nearWords, type Near } from "../../web/pages/milestones_near.ts";
21 import { withStanding } from "../../web/pages/wave_standing.ts";
22 import { doneWords } from "../../story/wave_moved.ts";
2123 import { sourceFor } from "../../view/source.ts";
2224 import type { Commit } from "../../view/source.ts";
2325 import type { Ctx, Screen } from "../app/app.ts";
@@ -81,6 +83,8 @@ export function chapterLines(groups: readonly Group[], keep: (l: Landing) => boo
8183 out.push({ row: { title, meta: metaOf(when, `${pulls.length} ${pulls.length === 1 ? "pull" : "pulls"}`) } });
8284 if (g.kind === "chapter" && g.wave !== undefined && !filtering) {
8385 out.push({ row: { title: ` ${g.wave.sentence}` } });
86 const m = g.wave.milestone;
87 if (m !== undefined && m.total > 0) out.push({ row: { title: ` The milestone: ${m.title}: ${doneWords(m)}` } });

New terminal row with no test: nothing fails if it is removed. Add one to test/tui-changelog-waves.test.ts covering a wave with a milestone and one without.

8488 for (const p of g.wave.pulls) out.push({ row: { title: ` #${p.number} ${plainTitle(p.title)}` }, pull: p.number });
8589 }
8690 for (const l of pulls) out.push({ row: { title: ` #${l.number} ${plainTitle(l.title)}`.trimEnd(), meta: ago(l.at) }, pull: l.number });
@@ -261,7 +265,7 @@ export function changelogScreen(f: Session, ctx: Ctx): Screen {
261265 pulls: [...served].filter(([, id]) => id === chapter.id).map(([n]) => n),
262266 }));
263267 const live = (landings?.live ?? []).filter((l) => l.repo.toLowerCase() === name.toLowerCase());
264 groups = groupByChapter(live, await withWaves(f.app, entries));
268 groups = groupByChapter(live, withStanding(f.app, await withWaves(f.app, entries), f.user));
265269 }
266270 near = nearLines(nearMilestones(f.app, f.app.config.forgeRepo, f.user)?.near ?? []);
267271 home();
src/web/pages/changelog.ts +16 −3
@@ -24,6 +24,8 @@ import { forgeChangelog, type ReleaseEntry } from "../../release/changelog.ts";
2424 import { comparePath, rangeOf, rangeWords } from "../../release/range.ts";
2525 import { gather, plainTitle, type Gathered } from "../../story/gather.ts";
2626 import { milestoneHref, progress } from "./milestones.ts";
27 import { doneWords } from "../../story/wave_moved.ts";
28 import { withStanding } from "./wave_standing.ts";
2729 import { nearMilestones, nearWords, type Near } from "./milestones_near.ts";
2830 import { liveRegionsJs } from "../client.ts";
2931 import { pageHead, repoBase } from "../chrome.ts";
@@ -129,6 +131,17 @@ export function chapterStamp(db: Database): string {
129131 return `${r?.n ?? 0}|${r?.last ?? ""}|${r?.seen ?? ""}|${r?.items ?? ""}|${Bun.hash(r?.placed ?? "").toString(36)}`;
130132 }
131133
134 /**
135 * What the newest wave's milestone line depends on: the last change to any issue of a repository
136 * that has a chapter, so closing an issue under the milestone moves the page's tag.
137 */
138 function standingStamp(db: Database): string {
139 const r = db
140 .query<{ last: string | null }, []>("SELECT max(updated_at) AS last FROM issue WHERE repo_id IN (SELECT repo_id FROM chapter WHERE state != 'draft')")
141 .get();
142 return r?.last ?? "";
143 }
144
132145 /**
133146 * A chapter: a nav row (its name linked to its page, its closing day or "open" as the trail), then
134147 * its landed pulls, one line each; a chapter nothing landed in says so on its row.
@@ -143,7 +156,7 @@ function chapterSection(g: Extract<Group, { kind: "chapter" }>, own: string | un
143156 href: `/${g.repo}/chapters/${c.name}`,
144157 nav: true,
145158 title: c.name,
146 ...(g.wave !== undefined ? { meta: html`${g.wave.sentence}` } : g.landings.length === 0 ? { meta: html`Nothing landed yet.` } : {}),
159 ...(g.wave !== undefined ? { meta: html`${g.wave.sentence}${g.wave.milestone === undefined || g.wave.milestone.total === 0 ? "" : html` <span data-wave-milestone>The milestone: ${g.wave.milestone.title}: ${doneWords(g.wave.milestone)}</span>`}` } : g.landings.length === 0 ? { meta: html`Nothing landed yet.` } : {}),
147160 trail: c.closedAt === null ? html`open` : time(c.closedAt, { date: true }),
148161 ...(g.wave === undefined ? {} : { data: { wave: "" } }),
149162 });
@@ -360,7 +373,7 @@ export async function changelogPage(ctx: Ctx): Promise<Response> {
360373 const everything = [...read.onItsWay, ...read.live];
361374 // One aggregate read stands for the chapters in the tag; the per-repository reads wait until the
362375 // tag has missed.
363 const stamp = chapterStamp(ctx.app.db);
376 const stamp = `${chapterStamp(ctx.app.db)}|${standingStamp(ctx.app.db)}`;
364377 // A closed chapter's wave lands after the close itself, so the tag holds what the waves say too
365378 // (#14221).
366379 const tips = await waveTips(ctx.app, read.live.map((l) => l.repo));
@@ -372,7 +385,7 @@ export async function changelogPage(ctx: Ctx): Promise<Response> {
372385 const tag = flashed ? undefined : changelogTag(read.version, everything, [choice, bet, read.commit, read.live.map((l) => `${l.repo}#${l.number}`), readable, toLive ?? null, everything.map((l) => timeAgo(l.at)), new Date().toISOString().slice(0, 10), releases?.entries[0]?.oid ?? null, releases?.entries.length ?? 0, ctx.auth.user?.id ?? null, ctx.auth.user?.isAdmin === true, ctx.theme ?? null, near, stamp, tips, read.more ?? null, ctx.url.searchParams.get("before") === null ? 0 : 1, target ?? null]);
373386 const keep = tag === undefined ? undefined : cacheHeaders(ctx, tag);
374387 if (keep !== undefined && keep.matched) return keep.response;
375 const chapters = await withWaves(ctx.app, chapterEntries(ctx.app.db, read.live, ctx.auth.user));
388 const chapters = withStanding(ctx.app, await withWaves(ctx.app, chapterEntries(ctx.app.db, read.live, ctx.auth.user)), ctx.auth.user);
376389 const rendering = performance.now();
377390 const filters = seg([
378391 ...(read.own === undefined ? [] : [{ label: "This forge", href: "/changelog", current: choice === read.own }]),
src/web/pages/wave_standing.ts added +34
@@ -0,0 +1,34 @@
1 /**
2 * How close the newest wave's big thing is, for the changelog's front: the widest milestone the
3 * wave's merged pulls moved, counted by the plan the milestone page reads (`planFor`), so the two
4 * never disagree. A wave that moved no milestone gets none, and nothing is said in its place.
5 */
6
7 import type { App } from "../../app.ts";
8 import { getRepo } from "../../core/repos.ts";
9 import type { User } from "../../core/users.ts";
10 import { newest, type ChapterEntry } from "../../release/chapter_groups.ts";
11 import { movedForViewer, widestMoved } from "../../story/wave_moved.ts";
12 import { planFor } from "./milestones.ts";
13
14 /** The entries, the newest one that wrote a wave carrying its widest moved milestone, if any. */
15 export function withStanding(app: App, entries: readonly ChapterEntry[], viewer: User | undefined): ChapterEntry[] {
16 const top = entries.filter((e) => e.wave !== undefined && e.canSee && e.chapter.state !== "draft").sort(newest)[0];
17 const wave = top?.wave;
18 if (top === undefined || wave === undefined) return [...entries];
19 const [o = "", n = ""] = top.repo.split("/");
20 const repo = getRepo(app.db, o, n);
21 if (repo === undefined) return [...entries];
22 const [owner, name] = [repo.ownerName, repo.name];
23 const moved = movedForViewer({
24 db: app.db,
25 repo,
26 refs: wave.pulls.map((p) => ({ owner, name, number: p.number })),
27 viewer,
28 plan: () => planFor({ app }, repo, false, new Date(), false),
29 });
30 const widest = widestMoved(moved);
31 if (widest === undefined) return [...entries];
outdated

top.wave! is redundant: top.wave was narrowed at the guard. Use a local const wave = top.wave.

32 const milestone = { title: widest.title, done: widest.done, total: widest.total };
33 return entries.map((e) => (e === top ? { ...e, wave: { ...wave, milestone } } : e));
34 }
test/changelog-wave-standing.test.ts added +91
@@ -0,0 +1,91 @@
1 /**
2 * The newest wave on /changelog says its milestone's "N of M done", counted as the milestone page
3 * counts it (#14502).
4 */
5 import { expect, test } from "bun:test";
6 import { mkdtempSync } from "node:fs";
7 import { tmpdir } from "node:os";
8 import { join } from "node:path";
9 import { newApp } from "../src/actions/apps.ts";
10 import { close, draft, fill, open } from "../src/actions/chapters.ts";
11 import { createApp } from "../src/app.ts";
12 import type { Chapter } from "../src/core/chapters.ts";
13 import { createIssue } from "../src/core/issues.ts";
14 import { getRepo } from "../src/core/repos.ts";
15 import { createUser } from "../src/core/users.ts";
16 import { repoDir } from "../src/git/repos.ts";
17 import { commitFiles } from "../src/git/write.ts";
18 import { serve } from "../src/http/server.ts";
19 import type { ChapterEntry } from "../src/release/chapter_groups.ts";
20 import type { Landing, Landings } from "../src/release/landings.ts";
21 import { shippedRegion } from "../src/web/pages/changelog.ts";
22
23 const chapter: Chapter = {
24 id: "c", repoId: "r", name: "v1", means: "done", state: "closed", position: 1, patchOf: null,
25 createdAt: "2026-10-01T10:00:00Z", openedAt: "2026-10-01T10:00:00Z", closedAt: "2026-10-06T10:00:00Z", tagOid: "abc", notes: "", costUsd: 1,
26 };
27 const landing: Landing = { repo: "a/b", number: 5, title: "Pull 5", at: "2026-10-05T10:00:00Z", live: true };
28 const read: Landings = { version: "1.0.0", commit: null, own: "a/b", live: [landing], onItsWay: [] };
29 const region = (milestone?: { title: string; done: number; total: number }): string => {
30 const wave = { version: "1.0.0", sentence: "Shipped one.", pulls: [], ...(milestone === undefined ? {} : { milestone }) };
31 const e: ChapterEntry = { repo: "a/b", chapter, canSee: true, pulls: [5], wave };
32 return String(shippedRegion(read, "a/b", new Date("2026-11-12T12:00:00Z"), "UTC", undefined, true, [e]));
33 };
34
35 test("the wave's heading shows its milestone's done over total, escaped; no milestone or an empty one shows nothing", () => {
36 expect(region({ title: "Big <b>", done: 2, total: 5 })).toContain("<span data-wave-milestone>The milestone: Big &lt;b&gt;: 2 of 5 done</span>");
37 expect(region()).not.toContain("data-wave-milestone");
38 expect(region({ title: "Empty", done: 0, total: 0 })).not.toContain("data-wave-milestone");
39 expect(region()).not.toContain("0 of 0");
40 });
41
42 test("served from the same count as the milestone page, on the newest wave only", async () => {
43 const app = createApp({ dataDir: mkdtempSync(join(tmpdir(), "forge-standing-")), port: 0, host: "forge.test" });
44 const servers = await serve(app);
45 try {
46 const u = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
47 if (!u.ok) throw new Error(u.error);
48 const a = await newApp(app, u.value, { name: "shop", description: "Words", visibility: "public" });
49 if (!a.ok) throw new Error(String(a.error));
50 const repo = getRepo(app.db, "alice", "shop")!;
51 const first = await commitFiles(repoDir(app.reposRoot, "alice", "shop"), { branch: repo.defaultBranch, message: "first", files: [{ path: "README.md", content: "hi" }], author: { name: "T", email: "[email protected]" } });
52 if (!first.ok) throw new Error("commit");
53 expect(draft(app, u.value, repo, { name: "v1.1.0" }).ok).toBe(true);
54 const umbrella = createIssue(app.db, { repoId: repo.id, authorId: u.value.id, title: "The big thing", body: "" });
55 if (!umbrella.ok) throw new Error(String(umbrella.error));
56 const waits = (id: string) => app.db.query("INSERT INTO issue_dependency (issue_id, blocked_by_id) VALUES (?1, ?2)").run(umbrella.value.id, id);
57 for (let k = 1; k <= 3; k++) {
58 const made = createIssue(app.db, { repoId: repo.id, authorId: u.value.id, title: `Item ${k}`, body: "" });
59 if (!made.ok) throw new Error(String(made.error));
60 app.db.query("UPDATE issue SET state = 'closed', closed_at = ?2 WHERE id = ?1").run(made.value.id, "2026-11-10T00:00:00.000Z");
61 waits(made.value.id);
62 const n = 7000 + k;
63 app.db.query(`INSERT INTO issue (id, repo_id, number, kind, title, body, author_id, state) VALUES (?1, ?2, ?3, 'pull', ?4, ?5, ?6, 'closed')`).run(`p${n}`, repo.id, n, `Build ${k}`, `Closes #${made.value.number}`, u.value.id);
64 app.db.query(`INSERT INTO pull (issue_id, base_branch, head_branch, base_oid, head_oid, merged_at) VALUES (?1, 'main', ?2, 'a', 'b', '2026-11-10T00:00:00.000Z')`).run(`p${n}`, `b${n}`);
65 app.db.query(`INSERT INTO release (sha, repo_id, pull_number, ok, line, created_at) VALUES ('abc', ?1, ?2, 1, 'ok', '2026-11-11T08:00:00.000Z')`).run(repo.id, n);
66 expect(fill(app, u.value, repo, "v1.1.0", made.value.number, true).ok).toBe(true);
67 }
68 const left = createIssue(app.db, { repoId: repo.id, authorId: u.value.id, title: "Still open", body: "" });
69 if (!left.ok) throw new Error(String(left.error));
70 waits(left.value.id);
71 expect(open(app, u.value, repo, "v1.1.0").ok).toBe(true);
72 expect((await close(app, u.value, repo, "v1.1.0", false, new Date("2026-11-16T12:00:00.000Z"))).ok).toBe(true);
73 const first200 = await fetch(`${servers.url}/changelog?repo=alice/shop`);
74 const page = await first200.text();
75 const etag = first200.headers.get("etag") ?? "";
76 expect(etag).not.toBe("");
77 const section = /<section class="mt" data-chapter="v1.1.0">.*?<\/section>/s.exec(page)?.[0] ?? "";
78 expect(section).toContain("<span data-wave-milestone>The milestone: The big thing: 3 of 4 done</span>");
79 const ms = await (await fetch(`${servers.url}/alice/shop/milestones`)).text();
80 expect(ms).toContain("3 of 4 done");
81 // Unchanged, the tag matches; closing an issue under the milestone moves it and the count.
82 expect((await fetch(`${servers.url}/changelog?repo=alice/shop`, { headers: { "if-none-match": etag } })).status).toBe(304);
83 app.db.query("UPDATE issue SET state = 'closed', closed_at = ?2, updated_at = ?2 WHERE id = ?1").run(left.value.id, "2099-01-01T00:00:00.000Z");
84 const after = await fetch(`${servers.url}/changelog?repo=alice/shop`, { headers: { "if-none-match": etag } });
85 expect(after.status).toBe(200);
86 expect(await after.text()).toContain("The milestone: The big thing: 4 of 4 done");
87 } finally {
88 servers.stop();
89 app.close();
90 }
91 }, 60_000);
test/tui-changelog.test.ts +12
@@ -184,3 +184,15 @@ test("a release row in the terminal names the commit range it holds, as the page
184184 expect(rows[1]!.meta).toContain("aaaaaaa");
185185 expect(rows[1]!.meta).not.toContain("…");
186186 });
187
188 test("the terminal's wave tells its milestone under the sentence; a wave with none or an empty one tells nothing", () => {
189 const chapter = {
190 id: "v1", repoId: "r", name: "v1", means: "m", state: "closed", position: 1, patchOf: null,
191 createdAt: "2026-10-01T00:00:00Z", openedAt: "2026-10-01T00:00:00Z", closedAt: "2026-10-25T00:00:00Z", tagOid: null, notes: "", costUsd: null,
192 } as const;
193 const titles = (milestone?: { title: string; done: number; total: number }): string[] =>
194 chapterLines([{ kind: "chapter", repo: "a/b", chapter, landings: [], wave: { version: "1.0.0", sentence: "Shipped it.", pulls: [], ...(milestone === undefined ? {} : { milestone }) } }]).map((l) => l.row.title);
195 expect(titles({ title: "Big", done: 3, total: 4 })).toEqual(["Chapter v1", " Shipped it.", " The milestone: Big: 3 of 4 done"]);
196 expect(titles()).toEqual(["Chapter v1", " Shipped it."]);
197 expect(titles({ title: "Empty", done: 0, total: 0 })).toEqual(["Chapter v1", " Shipped it."]);
198 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs