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
Check · Review · Land · Live done — Landed and live in production.
torque/forge:torque/14502-changelog-opens-on-the-newest-wave-with → main 7 commits fork 5 threads · 5 unresolved
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:" | ||
| 97 | 97 | ## A closed chapter's wave |
| 98 | 98 | |
| 99 | 99 | 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`. | |
src/release/chapter_groups.ts +1 −1
| @@ -30,7 +30,7 @@ export type Group = | ||
| 30 | 30 | | { readonly kind: "between"; readonly landings: readonly Landing[] }; |
| 31 | 31 | |
| 32 | 32 | /** 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 { | |
| 34 | 34 | const at = (e: ChapterEntry): number => (e.chapter.closedAt === null ? Infinity : Date.parse(e.chapter.closedAt)); |
| 35 | 35 | return at(b) === at(a) ? b.chapter.position - a.chapter.position : at(b) < at(a) ? -1 : 1; |
| 36 | 36 | } |
src/release/chapter_waves.ts +5
| @@ -21,6 +21,11 @@ export interface ChapterWave { | ||
| 21 | 21 | * number). |
| 22 | 22 | */ |
| 23 | 23 | readonly pulls: readonly { readonly title: string; readonly url: string; readonly number: number }[]; |
outdated
This block sits between the |
||
| 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 }; | |
| 24 | 29 | } |
| 25 | 30 | |
| 26 | 31 | /** |
src/tui/screens/changelog.ts +5 −1
| @@ -18,6 +18,8 @@ import { repoDir } from "../../git/repos.ts"; | ||
| 18 | 18 | import { forgeChangelog, type ReleaseEntry } from "../../release/changelog.ts"; |
| 19 | 19 | import { readLandings, type Landing } from "../../release/landings.ts"; |
| 20 | 20 | 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"; | |
| 21 | 23 | import { sourceFor } from "../../view/source.ts"; |
| 22 | 24 | import type { Commit } from "../../view/source.ts"; |
| 23 | 25 | import type { Ctx, Screen } from "../app/app.ts"; |
| @@ -81,6 +83,8 @@ export function chapterLines(groups: readonly Group[], keep: (l: Landing) => boo | ||
| 81 | 83 | out.push({ row: { title, meta: metaOf(when, `${pulls.length} ${pulls.length === 1 ? "pull" : "pulls"}`) } }); |
| 82 | 84 | if (g.kind === "chapter" && g.wave !== undefined && !filtering) { |
| 83 | 85 | 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. |
||
| 84 | 88 | for (const p of g.wave.pulls) out.push({ row: { title: ` #${p.number} ${plainTitle(p.title)}` }, pull: p.number }); |
| 85 | 89 | } |
| 86 | 90 | 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 { | ||
| 261 | 265 | pulls: [...served].filter(([, id]) => id === chapter.id).map(([n]) => n), |
| 262 | 266 | })); |
| 263 | 267 | 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)); | |
| 265 | 269 | } |
| 266 | 270 | near = nearLines(nearMilestones(f.app, f.app.config.forgeRepo, f.user)?.near ?? []); |
| 267 | 271 | home(); |
src/web/pages/changelog.ts +16 −3
| @@ -24,6 +24,8 @@ import { forgeChangelog, type ReleaseEntry } from "../../release/changelog.ts"; | ||
| 24 | 24 | import { comparePath, rangeOf, rangeWords } from "../../release/range.ts"; |
| 25 | 25 | import { gather, plainTitle, type Gathered } from "../../story/gather.ts"; |
| 26 | 26 | import { milestoneHref, progress } from "./milestones.ts"; |
| 27 | import { doneWords } from "../../story/wave_moved.ts"; | |
| 28 | import { withStanding } from "./wave_standing.ts"; | |
| 27 | 29 | import { nearMilestones, nearWords, type Near } from "./milestones_near.ts"; |
| 28 | 30 | import { liveRegionsJs } from "../client.ts"; |
| 29 | 31 | import { pageHead, repoBase } from "../chrome.ts"; |
| @@ -129,6 +131,17 @@ export function chapterStamp(db: Database): string { | ||
| 129 | 131 | return `${r?.n ?? 0}|${r?.last ?? ""}|${r?.seen ?? ""}|${r?.items ?? ""}|${Bun.hash(r?.placed ?? "").toString(36)}`; |
| 130 | 132 | } |
| 131 | 133 | |
| 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 | ||
| 132 | 145 | /** |
| 133 | 146 | * A chapter: a nav row (its name linked to its page, its closing day or "open" as the trail), then |
| 134 | 147 | * 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 | ||
| 143 | 156 | href: `/${g.repo}/chapters/${c.name}`, |
| 144 | 157 | nav: true, |
| 145 | 158 | 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.` } : {}), | |
| 147 | 160 | trail: c.closedAt === null ? html`open` : time(c.closedAt, { date: true }), |
| 148 | 161 | ...(g.wave === undefined ? {} : { data: { wave: "" } }), |
| 149 | 162 | }); |
| @@ -360,7 +373,7 @@ export async function changelogPage(ctx: Ctx): Promise<Response> { | ||
| 360 | 373 | const everything = [...read.onItsWay, ...read.live]; |
| 361 | 374 | // One aggregate read stands for the chapters in the tag; the per-repository reads wait until the |
| 362 | 375 | // tag has missed. |
| 363 | const stamp = chapterStamp(ctx.app.db); | |
| 376 | const stamp = `${chapterStamp(ctx.app.db)}|${standingStamp(ctx.app.db)}`; | |
| 364 | 377 | // A closed chapter's wave lands after the close itself, so the tag holds what the waves say too |
| 365 | 378 | // (#14221). |
| 366 | 379 | const tips = await waveTips(ctx.app, read.live.map((l) => l.repo)); |
| @@ -372,7 +385,7 @@ export async function changelogPage(ctx: Ctx): Promise<Response> { | ||
| 372 | 385 | 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]); |
| 373 | 386 | const keep = tag === undefined ? undefined : cacheHeaders(ctx, tag); |
| 374 | 387 | 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); | |
| 376 | 389 | const rendering = performance.now(); |
| 377 | 390 | const filters = seg([ |
| 378 | 391 | ...(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
|
||
| 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 <b>: 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 | ||
| 184 | 184 | expect(rows[1]!.meta).toContain("aaaaaaa"); |
| 185 | 185 | expect(rows[1]!.meta).not.toContain("…"); |
| 186 | 186 | }); |
| 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 | }); |
new above
offline
Says the page shows 'The milestone: <name>: N of M done'; the page shows '<name>: N of M done'. Align.