From e458e3724924360dfad1252358368ff090cc4dae Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sun, 25 Oct 2026 16:02:36 +0100 Subject: [PATCH] Hub: journal.json in the flat format Kira reads, at /data/journal.json One entry per merged pull request (with its roadmap item), game or launcher release, shipped roadmap item (post and announce) and weekly summary, newest first, ids stable forever: the feed kira's src/journal.js posts to #updates and X. The journal's item links are hub#; the board's and the journal's ids are reserved too, and the page-wide unique-id test covers every tab. Co-Authored-By: Claude Opus 5.5 --- roadmap/README.md | 36 ++++++++++++------ tools/roadmap.py | 2 +- website/README.md | 2 +- website/build.mjs | 2 +- website/src/hub.html | 2 +- website/src/hub.js | 79 ++++++++++++++++++++++++++++++++-------- website/src/hub.test.mjs | 51 +++++++++++++++++++++++--- 7 files changed, 136 insertions(+), 38 deletions(-) diff --git a/roadmap/README.md b/roadmap/README.md index f16e83f8c..55cf9d09f 100644 --- a/roadmap/README.md +++ b/roadmap/README.md @@ -53,7 +53,7 @@ Whoever moves the work (the orchestrator on each heartbeat, or anyone in their p 5. Once a week, write the week's summary in `roadmap/journal/-.md` (for example `2026-43.md`): `# Title`, a paragraph or two for players, then `## Technical` and the same week for contributors, with its pull requests. `build` puts it into website/data/roadmap.json; the hub's Journal tab - shows it among the releases, and `/hub/journal.json` carries it to Kira's #updates and to posts elsewhere. + shows it among the releases, and `/data/journal.json` carries it to Kira's #updates and to X. 6. Suggestions from the website and Discord are read and triaged by the maintainers. A good one becomes an item in a normal pull request; none is published automatically. @@ -62,18 +62,30 @@ or when the file breaks a rule; `python3 tools/roadmap.py check --offline` runs ## The journal -The hub's Journal tab and `https://playhorizon.dev/hub/journal.json` are built with each deploy of the website -(`website/src/hub.js`, `journalFrom`): every game and launcher release with its notes' changes, each placed under -the roadmap item it moves (the pull request's `roadmap:` label, else the item that links it); the merged pull -requests no release has yet; and the weekly summaries above. Its JSON, newest first: +The hub's Journal tab and `https://playhorizon.dev/data/journal.json` are built with each deploy of the website +(`website/src/hub.js`). The tab shows every game and launcher release with its notes' changes, each placed under +the roadmap item it moves (the pull request's `roadmap:` label, else the item that links it), the merged pull +requests no release has yet, and the weekly summaries above. + +`journal.json` is what Kira reads for `#updates` and its X posts (kira's `src/journal.js`): one flat entry per +merged pull request, release, shipped item and weekly summary, newest first, the latest 300. ```json -{ "format": "horizon-journal", "version": 1, "generated": "…", "url": "https://playhorizon.dev/hub#journal", - "entries": [ { "id": "v0.2.57", "kind": "release | launcher | merged | week", "date": "…", "title": "…", - "plain": "one line for players", "url": "…", "dev": "weeks only", - "changes": [ { "section": "new | fixed | merged", "text": "…", "prs": [1787], "item": "discord-presence" } ], - "items": [ { "id", "title", "plain", "post" } ], // roadmap items the entry moved - "shipped": [ { "id", "title", "plain", "post" } ] } ] } // items that shipped in this release +{ "format": "horizon-journal", "version": 2, "generated": "…", "url": "https://playhorizon.dev/hub#journal", + "entries": [ + { "id": "pr-1788", "kind": "merge", "date": "…", "title": "the pull request's title", "url": "…", + "number": 1788, "item": "discord-presence", "item_title": "Discord Rich Presence" }, + { "id": "release-v0.2.57", "kind": "release", "date": "…", "title": "…", "plain": "one line", "url": "…", + "tag": "v0.2.57" }, + { "id": "shipped-server-resource-packs", "kind": "shipped", "date": "the release's", "title": "…", + "plain": "…", "url": "https://playhorizon.dev/hub#server-resource-packs", "item": "…", "item_title": "…", + "shipped_in": "v0.2.48", "post": "at most 240 characters", "announce": false }, + { "id": "weekly-2026-43", "kind": "weekly", "date": "the week's last second", "title": "…", "plain": "…", + "dev": "…", "url": "https://playhorizon.dev/hub#week-2026-43" } ] } ``` -`post` is at most 240 characters, ready to announce as is. Readers should remember the ids they have posted. +- An `id` never changes: readers post each one once. `merge` entries are the pull requests players see (no + `skip-release` label), plus any that moves a roadmap item; `item` is absent when none does. +- `announce: true` (the item's `announce` key) asks Kira to post the shipped item on X too, with `post`. +- `https://playhorizon.dev/data/roadmap.json` is `roadmap.toml` as JSON (`areas`, `items` with every key above, + `overview`, the weekly summaries); an item's page is `https://playhorizon.dev/hub#`. diff --git a/tools/roadmap.py b/tools/roadmap.py index ab0147e70..fe97285ff 100644 --- a/tools/roadmap.py +++ b/tools/roadmap.py @@ -57,7 +57,7 @@ ISSUE = re.compile(r"#(\d+)$") ID = re.compile(r"[a-z0-9]+(-[a-z0-9]+)*$") # An item is the anchor playhorizon.dev/hub#: it can't take the name of a tab, a section or a heading. RESERVED = {"main", "overview", "roadmap", "board", "journal", "contribute", "hub-data", *STATUSES} -RESERVED_PREFIXES = ("h-", "tab-", "week-") +RESERVED_PREFIXES = ("h-", "tab-", "col-", "week-", "journal-") RELEASE = re.compile(r"(v\d[\w.]*|launcher@\d[\w.]*|launcher-v\d[\w.]*|website)$") MONTHS = ("January|February|March|April|June|July|August|September|October|November|December") # Kira's rule: no dates and no promises of when. "Coming soon" is the one allowed phrase. diff --git a/website/README.md b/website/README.md index 56fa515b9..d17bd0cd1 100644 --- a/website/README.md +++ b/website/README.md @@ -40,7 +40,7 @@ src/estimate.js estimates for unmeasured hardware from the nearest measured m src/markdown.js a small Markdown renderer (escapes everything), shared by build and page src/releases.js the home page's "Recently added" and the Releases page's markup, shared by build and page src/contributors.js the contributors' filtering and markup, shared by build and page -src/hub.js the hub's roadmap, board and journal from data/roadmap.json, GitHub's issues and the releases, shared by build and page; /hub/journal.json +src/hub.js the hub's roadmap, board and journal from data/roadmap.json, GitHub's issues and the releases, shared by build and page; /data/journal.json src/hub-page.js the hub page: tabs by #hash, the Simple / Technical switch (localStorage), the area filter, live states data/roadmap.json the roadmap, generated by tools/roadmap.py from roadmap/roadmap.toml (do not edit); served at /data/roadmap.json public/ fonts, screenshots, icons, og.png, robots.txt, benchmarks.json: copied as is (sitemap.xml is written by the build) diff --git a/website/build.mjs b/website/build.mjs index 17768e5fc..c3203891e 100644 --- a/website/build.mjs +++ b/website/build.mjs @@ -437,7 +437,7 @@ for (const { file, values: own } of docPages) { await mkdir(join(dist, "data"), { recursive: true }); await cp(join(site, "data", "roadmap.json"), join(dist, "data", "roadmap.json")); // The journal for Kira's #updates and its X posts: /data/journal.json, rebuilt with every deploy. -await writeFile(join(dist, "data", "journal.json"), JSON.stringify(journalJson(journal, roadmap), null, 1) + "\n"); +await writeFile(join(dist, "data", "journal.json"), JSON.stringify(journalJson(releases, hubLive, roadmap), null, 1) + "\n"); // The pages' inline scripts (they mark the page as scripted and apply the saved theme before CSS // applies) and the inlined stylesheet: the Content-Security-Policy in the Caddyfile allows them by hash. diff --git a/website/src/hub.html b/website/src/hub.html index a6e146080..d4ba4600c 100644 --- a/website/src/hub.html +++ b/website/src/hub.html @@ -71,7 +71,7 @@
-

Every release with what it changed, grouped by roadmap item in Technical, and a summary of each week. Also as journal.json.

+

Every release with what it changed, grouped by roadmap item in Technical, and a summary of each week. Also as journal.json.

{{HUB_JOURNAL}}
diff --git a/website/src/hub.js b/website/src/hub.js index cda3b4e5b..d293b7250 100644 --- a/website/src/hub.js +++ b/website/src/hub.js @@ -319,19 +319,66 @@ export function journalFrom(releases, list, roadmap) { return entries.sort((a, b) => b.date.localeCompare(a.date)).slice(0, ENTRIES); } -// /hub/journal.json: the journal for Kira's #updates and posts elsewhere, with each shipped item's short text. -export function journalJson(entries, roadmap, generated = new Date().toISOString()) { - const item = (id) => { - const i = roadmap.items.find((x) => x.id === id); - return i && { id: i.id, title: i.title, plain: i.plain, post: i.post || i.plain }; - }; - return { - format: "horizon-journal", - version: 1, - generated, - url: JOURNAL_URL, - entries: entries.map((e) => ({ ...e, items: [...new Set(e.changes.map((c) => c.item).filter(Boolean))].map(item).filter(Boolean), shipped: e.shipped.map(item).filter(Boolean) })), - }; +const HUB = "https://playhorizon.dev/hub"; +const FEED = 300; + +// /data/journal.json, which Kira reads for #updates and X (kira's src/journal.js): one flat entry per merged pull +// request, release, shipped roadmap item and weekly summary, newest first. An entry's id never changes: Kira posts +// each id once. Shipped items carry `post` (at most 240 characters, tools/roadmap.py checks) and `announce`. +export function journalJson(releases, list, roadmap, generated = new Date().toISOString()) { + const items = new Map(roadmap.items.map((i) => [i.id, i])); + const ours = releases.filter((r) => !r.draft && (isGame(r.tag_name) || isLauncher(r.tag_name))); + const published = new Map(ours.map((r) => [r.tag_name, r.published_at || ""])); + const merges = list + .filter((i) => i.kind === "pr" && i.state === "merged") + .map((pr) => ({ pr, item: itemOf(pr, roadmap) })) + // What players see, and anything that moves a roadmap item. + .filter(({ pr, item }) => item || !pr.labels.includes("skip-release")) + .map(({ pr, item }) => ({ + id: `pr-${pr.n}`, + kind: "merge", + date: pr.at, + title: pr.title, + url: pr.url, + number: pr.n, + ...(item ? { item, item_title: items.get(item)?.title } : {}), + })); + const released = ours.map((r) => ({ + id: `release-${r.tag_name}`, + kind: "release", + date: r.published_at || "", + title: r.name || r.tag_name, + plain: parts(r).line, + url: r.html_url, + tag: r.tag_name, + })); + const shipped = roadmap.items + .filter((i) => i.status === "shipped") + .map((i) => ({ + id: `shipped-${i.id}`, + kind: "shipped", + date: published.get(i.shipped_in) || generated, + title: i.title, + plain: i.plain, + url: `${HUB}#${i.id}`, + item: i.id, + item_title: i.title, + shipped_in: i.shipped_in, + post: i.post || i.plain, + announce: Boolean(i.announce), + })); + // A week's summary is dated at the end of its week, after that week's releases. + const weekly = (roadmap.journal || []).map((w) => ({ + id: `weekly-${w.week}`, + kind: "weekly", + date: new Date(Date.parse(w.date) + 7 * 864e5 - 1000).toISOString(), + title: w.title, + plain: w.plain, + dev: w.dev, + url: `${HUB}#week-${w.week}`, + })); + const entries = [...merges, ...released, ...shipped, ...weekly].sort((a, b) => b.date.localeCompare(a.date) || a.id.localeCompare(b.id)); + return { format: "horizon-journal", version: 2, generated, url: `${HUB}#journal`, entries: entries.slice(0, FEED) }; } const KIND = { release: "Game", launcher: "Launcher", merged: "Merged", week: "This week" }; @@ -349,7 +396,7 @@ function changesHtml(entry, roadmap) { const dev = `
${order .map((id) => { const item = roadmap.items.find((i) => i.id === id); - return `

${item ? `${escape(item.title)}` : "Other changes"}

    ${groups.get(id).map(line).join("")}
`; + return `

${item ? `${escape(item.title)}` : "Other changes"}

    ${groups.get(id).map(line).join("")}
`; }) .join("")}
`; return simple + dev; @@ -364,8 +411,8 @@ export function journalHtml(entries, roadmap) {

${e.url ? `${escape(e.title)}` : escape(e.title)}

${e.kind === "week" ? `

${inline(e.plain)}

${inline(e.dev.replace(/(^|[^\w[/`])#(\d+)\b/g, (_, b, n) => `${b}[#${n}](${issueUrl(n)})`))}

` : ""} - ${shipped.length ? `

Shipped: ${shipped.map((i) => `${escape(i.title)}`).join(", ")}

` : ""} - ${items.length ? `

${items.map((i) => `${escape(i.title)}`).join("")}

` : ""} + ${shipped.length ? `

Shipped: ${shipped.map((i) => `${escape(i.title)}`).join(", ")}

` : ""} + ${items.length ? `

${items.map((i) => `${escape(i.title)}`).join("")}

` : ""} ${changesHtml(e, roadmap)} `; }) diff --git a/website/src/hub.test.mjs b/website/src/hub.test.mjs index a6337399b..d688489e9 100644 --- a/website/src/hub.test.mjs +++ b/website/src/hub.test.mjs @@ -1,7 +1,7 @@ import { test } from "node:test"; import assert from "node:assert/strict"; import { readFileSync } from "node:fs"; -import { boardFrom, fixesIn, itemOf, journalFrom, journalHtml, journalJson, overviewHtml, progress, roadmapHtml, slimIssue } from "./hub.js"; +import { boardFrom, boardHtml, fixesIn, itemOf, journalFrom, journalHtml, journalJson, overviewHtml, progress, roadmapHtml, slimIssue } from "./hub.js"; const roadmap = JSON.parse(readFileSync(new URL("../data/roadmap.json", import.meta.url), "utf8")); @@ -42,7 +42,11 @@ test("the roadmap renders every item once, with both texts, in its status's sect }); test("an item is its own anchor (hub#, as Kira links it) and takes no other id of the page", () => { - const page = readFileSync(new URL("./hub.html", import.meta.url), "utf8") + roadmapHtml(roadmap) + overviewHtml(roadmap); + const week = { week: "2030-01", date: "2029-12-31", title: "A week", plain: "p", dev: "d" }; + const release = { tag_name: "v0.2.2", name: "0.2.2", published_at: "2030-01-02T00:00:00Z", html_url: "u", body: "" }; + const journal = journalHtml(journalFrom([release], [], { ...roadmap, journal: [week] }), roadmap); + const board = boardHtml(boardFrom([], roadmap), roadmap); + const page = readFileSync(new URL("./hub.html", import.meta.url), "utf8") + roadmapHtml(roadmap) + overviewHtml(roadmap) + board + journal; const ids = [...page.matchAll(/ id="([^"]+)"/g)].map((m) => m[1]); assert.deepEqual(ids.filter((id, i) => ids.indexOf(id) !== i), []); for (const item of roadmap.items) assert.ok(ids.includes(item.id), item.id); @@ -91,10 +95,45 @@ test("the journal groups a release's changes by roadmap item and lists what awai assert.deepEqual(entries.map((e) => e.id), ["next-release", "v0.2.2", "launcher@0.2.1"]); assert.deepEqual(entries[0].changes.map((c) => [c.prs, c.item]), [[[1788], "discord-presence"]]); assert.deepEqual(entries[1].changes.map((c) => [c.section, c.text, c.item]), [["new", "Discord Rich Presence", "discord-presence"], ["fixed", "A fix", null]]); - const json = journalJson(entries, roadmap, "now"); - assert.equal(json.format, "horizon-journal"); - assert.equal(json.entries[1].items[0].post.length <= 240, true); const html = journalHtml(entries, roadmap); - assert.ok(html.includes('href="#item-discord-presence"')); + assert.ok(html.includes('href="#discord-presence"')); assert.ok(html.includes("And 1 fix.")); }); + +test("journal.json is the flat feed Kira reads: merges, releases, shipped items, weeks, ids that never change", () => { + const releases = [ + { tag_name: "v0.2.48", name: "Horizon 0.2.48", published_at: "2030-01-02T00:00:00Z", html_url: "https://github.com/ludovic111/horizon/releases/tag/v0.2.48", body: "### New\n- Packs (#1)\n" }, + { tag_name: "nightly-1", name: "Nightly", published_at: "2030-01-03T00:00:00Z", html_url: "u", body: "" }, + ]; + const list = [ + pr(1788, { state: "closed", pull_request: { merged_at: "2030-01-04T00:00:00Z" }, html_url: "https://github.com/ludovic111/horizon/pull/1788" }), + pr(7, { state: "closed", pull_request: { merged_at: "2030-01-04T00:00:00Z" }, labels: [{ name: "skip-release" }] }), + pr(8, { state: "closed", pull_request: { merged_at: "2030-01-04T00:00:00Z" }, labels: [{ name: "skip-release" }, { name: "roadmap:lean-code" }] }), + pr(9), + ].map(slimIssue); + const week = { week: "2030-01", date: "2029-12-31", title: "A week", plain: "p", dev: "d" }; + const feed = journalJson(releases, list, { ...roadmap, journal: [week] }, "2030-01-05T00:00:00Z"); + const byId = new Map(feed.entries.map((e) => [e.id, e])); + // A merged pull request, with its roadmap item; skip-release ones only when they move an item; open ones never. + assert.deepEqual(byId.get("pr-1788"), { id: "pr-1788", kind: "merge", date: "2030-01-04T00:00:00Z", title: "PR 1788", url: "https://github.com/ludovic111/horizon/pull/1788", number: 1788, item: "discord-presence", item_title: "Discord Rich Presence" }); + assert.ok(!byId.has("pr-7") && byId.get("pr-8").item === "lean-code" && !byId.has("pr-9")); + // Game and launcher releases only. + assert.equal(byId.get("release-v0.2.48").tag, "v0.2.48"); + assert.ok(!byId.has("release-nightly-1")); + // Every shipped item, dated by its release when the feed has it, with its post and the announce flag. + const shipped = roadmap.items.filter((i) => i.status === "shipped"); + for (const item of shipped) { + const e = byId.get(`shipped-${item.id}`); + assert.equal(e.kind, "shipped"); + assert.equal(e.url, `https://playhorizon.dev/hub#${item.id}`); + assert.ok(e.post.length <= 240 && typeof e.announce === "boolean", item.id); + } + assert.equal(byId.get("shipped-server-resource-packs").date, "2030-01-02T00:00:00Z"); + assert.equal(byId.get("weekly-2030-01").date, "2030-01-06T23:59:59.000Z"); + // Newest first; every entry has what Kira needs, and links only where Kira shows them. + assert.deepEqual(feed.entries.map((e) => e.date), feed.entries.map((e) => e.date).sort().reverse()); + for (const e of feed.entries) { + assert.ok(e.id && ["merge", "release", "weekly", "shipped"].includes(e.kind) && e.date && e.title, e.id); + assert.match(e.url, /^https:\/\/(github\.com|playhorizon\.dev)\//, e.id); + } +});