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#<id>; 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 <noreply@anthropic.com>
This commit is contained in:
+24
-12
@@ -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/<year>-<ISO week>.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:<id>` 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:<id>` 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#<id>`.
|
||||
|
||||
+1
-1
@@ -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#<id>: 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.
|
||||
|
||||
+1
-1
@@ -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)
|
||||
|
||||
+1
-1
@@ -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.
|
||||
|
||||
@@ -71,7 +71,7 @@
|
||||
</div>
|
||||
|
||||
<div class="hub-panel" role="tabpanel" id="journal" aria-labelledby="tab-journal">
|
||||
<p class="hub-intro">Every release with what it changed, grouped by roadmap item in Technical, and a summary of each week. Also as <a href="/hub/journal.json">journal.json</a>.</p>
|
||||
<p class="hub-intro">Every release with what it changed, grouped by roadmap item in Technical, and a summary of each week. Also as <a href="/data/journal.json">journal.json</a>.</p>
|
||||
<div class="hub-journal" data-journal>
|
||||
{{HUB_JOURNAL}}
|
||||
</div>
|
||||
|
||||
+63
-16
@@ -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 = `<div class="hub-dev">${order
|
||||
.map((id) => {
|
||||
const item = roadmap.items.find((i) => i.id === id);
|
||||
return `<p class="hub-group">${item ? `<a href="#item-${escape(id)}">${escape(item.title)}</a>` : "Other changes"}</p><ul class="hub-changes">${groups.get(id).map(line).join("")}</ul>`;
|
||||
return `<p class="hub-group">${item ? `<a href="#${escape(id)}">${escape(item.title)}</a>` : "Other changes"}</p><ul class="hub-changes">${groups.get(id).map(line).join("")}</ul>`;
|
||||
})
|
||||
.join("")}</div>`;
|
||||
return simple + dev;
|
||||
@@ -364,8 +411,8 @@ export function journalHtml(entries, roadmap) {
|
||||
<p class="hub-entry-meta"><span class="badge${e.kind === "release" ? " badge-game" : e.kind === "launcher" ? " badge-launcher" : ""}">${KIND[e.kind]}</span><time datetime="${escape(e.date)}">${escape(e.date.slice(0, 10))}</time></p>
|
||||
<h3 class="hub-entry-title">${e.url ? `<a href="${escape(e.url)}">${escape(e.title)}</a>` : escape(e.title)}</h3>
|
||||
${e.kind === "week" ? `<p class="hub-plain">${inline(e.plain)}</p><p class="hub-dev">${inline(e.dev.replace(/(^|[^\w[/`])#(\d+)\b/g, (_, b, n) => `${b}[#${n}](${issueUrl(n)})`))}</p>` : ""}
|
||||
${shipped.length ? `<p class="hub-shipped">Shipped: ${shipped.map((i) => `<a href="#item-${escape(i.id)}">${escape(i.title)}</a>`).join(", ")}</p>` : ""}
|
||||
${items.length ? `<p class="hub-entry-items hub-plain">${items.map((i) => `<a class="hub-link" href="#item-${escape(i.id)}">${escape(i.title)}</a>`).join("")}</p>` : ""}
|
||||
${shipped.length ? `<p class="hub-shipped">Shipped: ${shipped.map((i) => `<a href="#${escape(i.id)}">${escape(i.title)}</a>`).join(", ")}</p>` : ""}
|
||||
${items.length ? `<p class="hub-entry-items hub-plain">${items.map((i) => `<a class="hub-link" href="#${escape(i.id)}">${escape(i.title)}</a>`).join("")}</p>` : ""}
|
||||
${changesHtml(e, roadmap)}
|
||||
</article>`;
|
||||
})
|
||||
|
||||
@@ -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#<id>, 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);
|
||||
}
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user