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

Closing a chapter writes its wave: one changelog entry naming what shipped, linked to the pulls #14087

Merged opened this

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

Merged

scout/forge:scout/14053-closing-a-chapter-writes-its-wave-one-ch → main 6 commits fork 3 threads · 3 unresolved

  • Merged. scout/14053-closing-a-chapter-writes-its-wave-one-ch was merged into main as 90ebdcb.

Review

Sign in to review this change.
6 files changed +301 −5
docs/features/README.md +1
@@ -184,6 +184,7 @@ Read with the guide page [Tell the crew](../guide-tell-the-crew.md).
184184 - [The thank-you note](thanks.md)
185185 - [The week is one budget for the whole crew](crew-week.md)
186186 - [The week's pace](week-pace.md)
187 - [Closing a chapter writes its wave](chapter-wave.md)
187188 - [Walking a wave](wave-walk.md)
188189 - [The wave-standing line](wave-standing.md)
189190 - [How many of a wave's changes are live and waiting to ship](wave-landing.md)
docs/features/chapter-wave.md added +36
@@ -0,0 +1,36 @@
1 # Closing a chapter writes its wave
2
3 Closing a chapter, in the web page or in the terminal, writes the chapter's
4 wave: `waves/<version>.md` on the repository's default branch, committed as the
5 person who closed it (`Wave <version>: <name> closed`).
6
7 ## What it holds
8
9 - The version: the chapter's name without the `v`, filled out to three parts
10 (`v1.1.0` is 1.1.0, `v2` is 2.0.0, `1.4` is 1.4.0).
11 - The date the chapter closed.
12 - One plain sentence naming what shipped: `v1.1.0 shipped 12 changes: Item 1,
13 Item 2, Item 3, and 9 more.`
14 - A highlight for each of up to five shipped issues.
15 - Links to up to ten of the pulls that shipped them, each pull once.
16
17 ## Where it lands
18
19 On the repository's waves page, `/<owner>/<repo>/waves/<version>`, and on the waves screen in the terminal,
20 like any hand-written wave.
21
22 ## When no wave is written
23
24 - The chapter's name is not a version (a chapter called `alpha`).
25 - Nothing in the chapter is done.
26 - A wave file for that version is already there. A reopen and a re-close leaves
27 the file alone, so a wave you edited by hand keeps your words.
28 - The write fails. The chapter is closed either way; the failure is logged.
29
30 ## Choices
31
32 A hand-written wave needs three to five highlights (`checkWave`). A chapter's
33 wave is built from what shipped, so it may have one to five.
34
35 The wave is committed straight to the default branch, not proposed as a pull,
36 so it does not go through the pull queue. `cut_wave` is the way to propose one.
src/actions/chapter_wave.ts added +48
@@ -0,0 +1,48 @@
1 /**

Needs docs/features/chapter-wave.md as the how-to (both doors rule).

2 * Closing a chapter writes its wave: `waves/<version>.md` on the default branch, one plain sentence
3 * of what shipped and links to up to ten of the pulls that shipped it, which /changelog and the
4 * waves page read. Once per chapter: a wave file already there is left alone. It never stops a
5 * close; the book is closed either way. The words are `story/wave.ts`'s.
6 */
7
8 import type { App } from "../app.ts";
9 import { itemsOf, type Chapter } from "../core/chapters.ts";
10 import { getPull } from "../core/pulls.ts";
11 import type { Repo } from "../core/repos.ts";
12 import type { User } from "../core/users.ts";
13 import { listTree } from "../git/read.ts";
14 import { repoDir } from "../git/repos.ts";
15 import { chapterWave, versionOfChapter, wavePath, writeWave, type ShippedItem } from "../story/wave.ts";
16 import { editFiles } from "./contents.ts";
17
18 /** Write the wave of a chapter just closed; true when a file was written. */
19 export async function writeChapterWave(app: App, actor: User, repo: Repo, chapter: Chapter): Promise<boolean> {
20 try {
21 const version = versionOfChapter(chapter.name);
22 if (version === undefined) return false;
23 const dir = repoDir(app.reposRoot, repo.ownerName, repo.name);
24 const tree = await listTree(dir, repo.defaultBranch, "waves");
25 if (tree.ok && tree.value.some((e) => e.name === `${version}.md`)) return false;
26 const shipped: ShippedItem[] = itemsOf(app.db, chapter)
27 .filter((i) => i.status === "done")
28 .map((i) => ({ number: i.number, title: i.title, pull: i.pull, pullTitle: i.pull === null ? "" : (getPull(app.db, repo.id, i.pull)?.title ?? "") }));
29 const base = (app.config.url ?? `http://localhost:${app.config.port}`).replace(/\/+$/, "");
30 const wave = chapterWave({
31 name: chapter.name,
32 date: (chapter.closedAt ?? new Date().toISOString()).slice(0, 10),
33 shipped,
34 link: (n) => `${base}/${repo.ownerName}/${repo.name}/pulls/${n}`,
35 });
36 if (!wave.ok) return false;
37 const text = writeWave(wave.value);
38 if (!text.ok) return false;
39 const done = await editFiles(app, actor, repo, {
40 message: `Wave ${version}: ${chapter.name} closed`,
41 files: [{ path: wavePath(version), content: text.value }],
42 });
43 return done.ok;
44 } catch (e) {
45 console.error(`chapter ${chapter.name}: its wave could not be written: ${String(e)}`);
46 return false;
47 }
48 }
src/actions/chapters.ts +5 −1
@@ -36,6 +36,7 @@ import { currentProof, line, probes, type Proof, type Result as ProbeResult } fr
3636 import { runGit } from "../git/env.ts";
3737 import { repoDir } from "../git/repos.ts";
3838 import { err, ok, type Result } from "../kernel/result.ts";
39 import { writeChapterWave } from "./chapter_wave.ts";
3940
4041 export type ChapterActError = ChapterError | "forbidden" | "no_issue" | "unfinished" | "no_branch" | "tag_exists" | "git" | "too_late" | "moved" | "another_open" | "unproven";
4142
@@ -326,7 +327,10 @@ export async function close(
326327 return err(getChapter(app.db, repo.id, name)?.state === "closed" ? "closed" : "git");
327328 }
328329 app.bus.append({ kind: "chapter.closed", repoId: repo.id, actorId: by.id, payload: { name, tag: chapter.name, shipped: landed.length, moved: left.length, ...(next === undefined ? {} : { into: next.name }) } });
329 return ok(getChapter(app.db, repo.id, name)!);
330 const closedChapter = getChapter(app.db, repo.id, name)!;
331 // The wave is the chapter's entry in the changelog; a failure to write it never undoes the close.
332 await writeChapterWave(app, by, repo, closedChapter);
333 return ok(closedChapter);
330334 }
331335
332336 /** Open a patch chapter for a closed one, with one click: drafted and opened together. */
src/story/wave.ts +65 −4
@@ -38,6 +38,8 @@ export type WaveResult<T> =
3838 | { ok: false; error: Error };
3939
4040 export const MIN_HIGHLIGHTS = 3;
outdated

Do not lower the floor for all waves; keep 3 here and restore the deleted test in test/waves.test.ts. Give chapterWave its own minimum.

41 /** A chapter's wave names what shipped, however little: its own floor. */
42 export const MIN_CHAPTER_HIGHLIGHTS = 1;
4143 export const MAX_HIGHLIGHTS = 5;
4244
4345 /** The shape of a wave's version, and of its file name before `.md`. */
@@ -70,7 +72,7 @@ const safeUrl = (s: string): boolean => {
7072 };
7173
7274 /** Check a wave's shape; the reason names `path`. */
73 export function checkWave(path: string, w: Wave): WaveResult<Wave> {
75 export function checkWave(path: string, w: Wave, min: number = MIN_HIGHLIGHTS): WaveResult<Wave> {
7476 if (!oneLine(w.version)) return fail(path, "missing version");
7577 if (!VERSION.test(w.version)) return fail(path, `bad version "${w.version}"`);
7678 if (!oneLine(w.date)) return fail(path, "missing date");
@@ -78,10 +80,10 @@ export function checkWave(path: string, w: Wave): WaveResult<Wave> {
7880 if (!oneLine(w.headline)) return fail(path, "missing headline");
7981 const hs = w.highlights;
8082 if (!Array.isArray(hs) || hs.length === 0) return fail(path, "no highlights");
81 if (hs.length < MIN_HIGHLIGHTS)
82 return fail(path, `too few highlights: ${hs.length}, want ${MIN_HIGHLIGHTS} to ${MAX_HIGHLIGHTS}`);
83 if (hs.length < min)
84 return fail(path, `too few highlights: ${hs.length}, want ${min} to ${MAX_HIGHLIGHTS}`);
8385 if (hs.length > MAX_HIGHLIGHTS)
84 return fail(path, `too many highlights: ${hs.length}, want ${MIN_HIGHLIGHTS} to ${MAX_HIGHLIGHTS}`);
86 return fail(path, `too many highlights: ${hs.length}, want ${min} to ${MAX_HIGHLIGHTS}`);
8587 for (const [i, h] of hs.entries()) {
8688 if (!oneLine(h?.title) || h.title.includes(SEP))
8789 return fail(path, `highlight ${i + 1} has no usable title`);
@@ -166,3 +168,62 @@ export function writeWave(w: Wave): WaveResult<string> {
166168 ];
167169 return { ok: true, value: out.join("\n") };
168170 }
171
172 /** The most pulls a closed chapter's wave links. */
173 export const MAX_CHAPTER_PULLS = 10;
174
175 const flat = (s: string): string => s.replace(/[\[\]]/g, "").replace(/\s+/g, " ").trim();
176
177 /**
178 * The version a chapter's name stands for: `v1.2.0` is 1.2.0, `v2` is 2.0.0, `1.4` is 1.4.0; a name
179 * that is no version (a chapter called "alpha") has none, and then no wave is written.
180 */
181 export function versionOfChapter(name: string): string | undefined {
182 const m = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(-[0-9A-Za-z.-]+)?$/.exec(name);
183 if (!m) return undefined;
184 const v = `${m[1]}.${m[2] ?? 0}.${m[3] ?? 0}${m[4] ?? ""}`;
185 return VERSION.test(v) ? v : undefined;
186 }
187
188 export interface ShippedItem {
189 number: number;
190 title: string;
191 /** The merged pull that shipped it. */
192 pull: number | null;
193 pullTitle: string;
194 }
195
196 /**
197 * The wave a closed chapter writes: one plain sentence naming what shipped, up to five highlights
198 * (the shipped issues) and links to up to ten of the pulls that shipped them. Plain data in;
199 * nothing shipped, or a name that is no version, is no wave.
200 */
201 export function chapterWave(input: {
202 name: string;
203 date: string;
204 shipped: readonly ShippedItem[];
205 link: (pull: number) => string;
206 }): WaveResult<Wave> {
207 const version = versionOfChapter(input.name);
208 const path = wavePath(version ?? input.name);
209 if (version === undefined) return fail(path, `${input.name} is not a version`);
210 if (input.shipped.length === 0) return fail(path, "nothing shipped");
211 const titles = input.shipped.map((i) => flat(i.title).replaceAll(SEP, " - "));
212 const shown = titles.slice(0, 3).join(", ");
213 const rest = titles.length - 3;
214 const n = input.shipped.length;
215 const headline = `${input.name} shipped ${n} ${n === 1 ? "change" : "changes"}: ${shown}${rest > 0 ? `, and ${rest} more` : ""}.`;
216 const seen = new Set<number>();
217 const pulls: WavePull[] = [];
218 for (const i of input.shipped) {
219 if (i.pull === null || seen.has(i.pull) || pulls.length >= MAX_CHAPTER_PULLS) continue;
220 seen.add(i.pull);
221 pulls.push({ title: `#${i.pull} ${flat(i.pullTitle) || "Pull"}`, url: input.link(i.pull) });
222 }
223 const highlights = input.shipped.slice(0, MAX_HIGHLIGHTS).map((i, k) => ({
224 title: titles[k]! || `Issue #${i.number}`,
225 why: i.pull === null ? `Issue #${i.number}, done in ${input.name}.` : `Issue #${i.number}, shipped by pull #${i.pull}.`,
226 }));
227 const wave: Wave = { version, date: input.date, headline, highlights, pulls };
228 return checkWave(path, wave, MIN_CHAPTER_HIGHLIGHTS);
229 }
test/chapter-wave.test.ts added +146
@@ -0,0 +1,146 @@
1 /**
2 * Closing a chapter writes its wave once: a plain sentence and links to up to ten pulls (#14053).
3 */
4 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
5 import { mkdtemp, rm } from "node:fs/promises";
6 import { tmpdir } from "node:os";
7 import { join } from "node:path";
8 import { newApp } from "../src/actions/apps.ts";
9 import { close, draft, fill, open, reopen } from "../src/actions/chapters.ts";
10 import { createApp, type App } from "../src/app.ts";
11 import { serve, type Servers } from "../src/http/server.ts";
12 import { createIssue } from "../src/core/issues.ts";
13 import { getRepo, type Repo } from "../src/core/repos.ts";
14 import { createUser, type User } from "../src/core/users.ts";
15 import { repoDir } from "../src/git/repos.ts";
16 import { commitFiles } from "../src/git/write.ts";
17 import { readWaves } from "../src/story/waves.ts";
18 import { chapterWave, versionOfChapter, writeWave } from "../src/story/wave.ts";
19 import { quietLogs } from "./helpers/globals.ts";
20
21 quietLogs();
22
23 describe("chapterWave (pure)", () => {
24 const item = (n: number, pull: number | null, title = `Thing ${n}`) => ({ number: n, title, pull, pullTitle: `Build ${n}` });
25 const link = (n: number) => `https://f.test/o/r/pulls/${n}`;
26
27 test("a chapter's name is its version, or nothing", () => {
28 expect(versionOfChapter("v1.2.3")).toBe("1.2.3");
29 expect(versionOfChapter("v2")).toBe("2.0.0");
30 expect(versionOfChapter("1.4")).toBe("1.4.0");
31 expect(versionOfChapter("alpha")).toBeUndefined();
32 });
33
34 test("one sentence, at most ten pulls, each once", () => {
35 const shipped = Array.from({ length: 14 }, (_, i) => item(i + 1, i < 13 ? i + 100 : null));
36 const w = chapterWave({ name: "v1.1.0", date: "2026-11-16", shipped: [...shipped, item(99, 100)], link });
37 if (!w.ok) throw w.error;
38 expect(w.value.headline).toBe("v1.1.0 shipped 15 changes: Thing 1, Thing 2, Thing 3, and 12 more.");
39 expect(w.value.pulls).toHaveLength(10);
40 expect(new Set(w.value.pulls.map((p) => p.url)).size).toBe(10);
41 expect(w.value.highlights).toHaveLength(5);
42 });
43
44 test("nothing shipped, or no version, is no wave", () => {
45 expect(chapterWave({ name: "v1.1.0", date: "2026-11-16", shipped: [], link }).ok).toBe(false);
46 expect(chapterWave({ name: "alpha", date: "2026-11-16", shipped: [item(1, 2)], link }).ok).toBe(false);
47 });
48
49 test("titles that would break the file's syntax are made safe", () => {
50 const w = chapterWave({ name: "v1.1.0", date: "2026-11-16", shipped: [item(1, 2, "A — [b]\nc")], link });
51 expect(w.ok).toBe(true);
52 });
53 });
54
55 const byHand = (): string => {
56 const h = (t: string) => ({ title: t, why: `why ${t}` });
57 const r = writeWave({ version: "1.1.0", date: "2026-11-16", headline: "Written by hand", highlights: [h("A"), h("B"), h("C")], pulls: [] });
58 if (!r.ok) throw r.error;
59 return r.value;
60 };
61
62 describe("closing a chapter", () => {
63 let dataDir = "";
64 let app: App;
65 let owner: User;
66 let repo: Repo;
67 let servers: Servers;
68 const wavesOf = async () => (await readWaves(repoDir(app.reposRoot, "alice", "shop"), repo.defaultBranch)).flatMap((e) => (e.ok ? [e.wave] : []));
69
70 beforeAll(async () => {
71 dataDir = await mkdtemp(join(tmpdir(), "forge-chapter-wave-"));
72 app = createApp({ dataDir, port: 0, host: "forge.test" });
73 const made = await createUser(app.db, { username: "alice", email: "[email protected]", password: "a-good-passphrase", origin: "seed", trusted: true, adminIfFirst: true });
74 if (!made.ok) throw new Error(String(made.error));
75 owner = made.value;
76 servers = await serve(app);
77 const a = await newApp(app, owner, { name: "shop", description: "Words", visibility: "public" });
78 if (!a.ok) throw new Error(String(a.error));
79 repo = getRepo(app.db, "alice", "shop")!;
80 const c = await commitFiles(repoDir(app.reposRoot, "alice", "shop"), {
81 branch: repo.defaultBranch,
82 message: "first",
83 files: [{ path: "README.md", content: "hello" }],
84 author: { name: "T", email: "[email protected]" },
85 });
86 if (!c.ok) throw new Error(JSON.stringify(c.error));
87 }, 30_000);
88
89 afterAll(async () => {
90 servers?.stop();
91 app.close();
92 await rm(dataDir, { recursive: true, force: true, maxRetries: 20, retryDelay: 100 });
93 });
94
95 test("writes the wave once, naming what shipped, linked to its pulls", async () => {
96 expect(draft(app, owner, repo, { name: "v1.1.0" }).ok).toBe(true);
97 for (let k = 1; k <= 12; k++) {
98 const made = createIssue(app.db, { repoId: repo.id, authorId: owner.id, title: `Item ${k}`, body: "" });
99 if (!made.ok) throw new Error(String(made.error));
100 const issue = made.value;
101 app.db.query("UPDATE issue SET state = 'closed', closed_at = ?2 WHERE id = ?1").run(issue.id, "2026-11-10T00:00:00.000Z");
102 const n = 7000 + k;
103 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 #${issue.number}`, owner.id);
104 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}`);
105 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);
106 expect(fill(app, owner, repo, "v1.1.0", issue.number, true).ok).toBe(true);
107 }
108 expect(open(app, owner, repo, "v1.1.0").ok).toBe(true);
109 expect((await close(app, owner, repo, "v1.1.0", false, new Date("2026-11-16T12:00:00.000Z"))).ok).toBe(true);
110
111 const waves = await wavesOf();
112 expect(waves).toHaveLength(1);
113 expect(waves[0]!.version).toBe("1.1.0");
114 expect(waves[0]!.date).toBe("2026-11-16");
115 expect(waves[0]!.headline).toContain("v1.1.0 shipped 12 changes");
116 expect(waves[0]!.pulls).toHaveLength(10);
117 expect(waves[0]!.pulls[0]!.url).toContain("/alice/shop/pulls/7001");
118 });
119
120 test("the wave page and the changelog carry the sentence and the pull links", async () => {
121 const page = await (await fetch(`${servers.url}/alice/shop/waves/1.1.0`)).text();
122 expect(page).toContain("v1.1.0 shipped 12 changes: Item 1, Item 2, Item 3, and 9 more.");
123 expect(page).toContain("/alice/shop/pulls/7001");
124 expect(page).toContain("/alice/shop/pulls/7010");
125 expect(page).not.toContain("/alice/shop/pulls/7011");
126 const log = await (await fetch(`${servers.url}/changelog`)).text();
127 expect(log).toContain("v1.1.0");
128 });
129
130 test("closing twice writes it once: a wave already there is left alone", async () => {
131 expect(await close(app, owner, repo, "v1.1.0", false)).toEqual({ ok: false, error: "closed" });
132 // A person edits the wave by hand; taken back and closed again, their words stay.
133 const edited = await commitFiles(repoDir(app.reposRoot, "alice", "shop"), {
134 branch: repo.defaultBranch,
135 message: "hand-written wave",
136 files: [{ path: "waves/1.1.0.md", content: byHand() }],
137 author: { name: "T", email: "[email protected]" },
138 });
139 if (!edited.ok) throw new Error(JSON.stringify(edited.error));
140 expect((await reopen(app, owner, repo, "v1.1.0", Date.parse("2026-11-16T12:00:30.000Z"))).ok).toBe(true);
141 expect((await close(app, owner, repo, "v1.1.0", false, new Date("2026-11-16T12:05:00.000Z"))).ok).toBe(true);
142 const waves = await wavesOf();
143 expect(waves).toHaveLength(1);
144 expect(waves[0]!.headline).toBe("Written by hand");
145 });
146 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs