Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@ All notable changes to this site are recorded here. The format follows

## [Unreleased]

### Added
- Editing a release's notes on GitHub now updates the app page's "What's new" within the hour.
Before, the site took the notes once, when the version arrived, and kept them.

## [1.7.0] — 2026-11-09

### Added
Expand Down
10 changes: 8 additions & 2 deletions releases/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ download button's "New" pill, for the seven days the release counts as new.
version: '1.2.25' # must equal release.version in apps/<slug>.md — the build checks
date: 2026-10-12 # the release day, in Korea
url: https://github.com/…/releases/tag/v1.2.25
source: 52047d8904a3 # which GitHub notes this came from — written by the sync
---

The release notes, as written, cut down sentence by sentence: no HTML tags or images,
Expand All @@ -19,5 +20,10 @@ address or CHANGELOG.md (tools/sync-lib.mjs, cleanNotes).

**Required while the release is new.** The build fails for an app whose release is in its
seven new days and has no file here, or an empty one — so every app's pill comes with its
description. You can edit the text; the next release replaces the file. The sync writes it when a new
release arrives, or when the file is missing.
description. The sync writes it when a new release arrives, when the file is missing, and when
the release's notes are edited on GitHub (within the hour). You can edit the text here too: a
`source:` line records which GitHub notes the file came from, so a hand edit lasts until the
release's own notes change or the next release arrives.
(Keep that line when you edit: a file without one is compared by its text and rewritten.)
Edited notes that would leave nothing to show, or that use a phrase `npm run check` refuses,
are not taken: the page keeps what it has, and one Issue says why until the notes are fixed.
60 changes: 57 additions & 3 deletions tests/sync.test.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
// Tests for tools/sync-lib.mjs — the parts of the hourly app sync that need no network.
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { cleanNotes, compareVersions, kstDate, planApp, releaseField, setReleaseField, signersOf } from '../tools/sync-lib.mjs';
import { cleanNotes, compareVersions, kstDate, notesFile, planApp, releaseField, setReleaseField, signersOf } from '../tools/sync-lib.mjs';

const md = `---
name: X
Expand Down Expand Up @@ -103,7 +103,8 @@ release:
signer: ${SIGNER}
${extra}---
`;
const app = (extra = '') => ({ slug: 'x', md: appMd(extra), readme: `${OLD} x.apk\n`, notesExists: true });
const served = (notes = 'Better.') => notesFile({ version: '1.0.0', date: '2026-10-12', url: 'https://github.com/o/x/releases/tag/v1.0.0', notes });
const app = (extra = '') => ({ slug: 'x', md: appMd(extra), readme: `${OLD} x.apk\n`, notes: served() as string | null });
const rel = (tag = 'v1.1.0', assets = [{ name: 'x.apk', browser_download_url: 'https://dl/x.apk' }]) => ({
tag_name: tag, published_at: '2026-10-12T09:00:00Z', html_url: 'https://github.com/o/x/releases/tag/' + tag,
body: 'Better.', assets,
Expand Down Expand Up @@ -134,14 +135,67 @@ test('a release whose notes clean down to nothing is refused, and writes nothing
const empty = (body: string | null) => ({ ...rel(), body });
await assert.rejects(planApp(app(), empty(null), io()), /no release notes/);
await assert.rejects(planApp(app(), empty('SHA-256 ' + 'a'.repeat(64)), io()), /no release notes/);
await assert.rejects(planApp({ ...app(), notesExists: false }, { ...rel('v1.0.0'), body: '' }, io()), /no release notes/);
await assert.rejects(planApp({ ...app(), notes: null }, { ...rel('v1.0.0'), body: '' }, io()), /no release notes/);
});

test('the same or an older release changes nothing', async () => {
assert.deepEqual((await planApp(app(), rel('v1.0.0'), io())).writes, []);
assert.deepEqual((await planApp(app(), rel('v0.9.0'), io())).writes, []);
});

test("a release whose notes were edited on GitHub rewrites the page's notes, and only those", async () => {
const plan = await planApp(app(), { ...rel('v1.0.0'), body: 'Better, and faster.' }, io());
assert.equal(plan.change, 'x: release notes for 1.0.0 updated');
assert.deepEqual(plan.writes.map(([p]) => p), ['releases/x.md']);
const file = String(plan.writes[0][1]);
assert.match(file, /\n\nBetter, and faster\.\n$/);
assert.match(file, /^version: '1\.0\.0'$/m);
assert.match(file, /^date: 2026-10-12$/m);
// Written again from the new text, it matches, so the next hourly run changes nothing.
assert.deepEqual((await planApp({ ...app(), notes: String(plan.writes[0][1]) }, { ...rel('v1.0.0'), body: 'Better, and faster.' }, io())).writes, []);
});

test("notes the page can show say so, so a refused-notes Issue closes; a new version says nothing", async () => {
assert.deepEqual((await planApp(app(), rel('v1.0.0'), io())).notes, { held: null });
// A rewrite is not live until its candidate passes, so the Issue waits for the next run.
assert.equal((await planApp(app(), { ...rel('v1.0.0'), body: 'Edited.' }, io())).notes, undefined);
assert.equal((await planApp(app(), rel(), io())).notes, undefined);
});

test('a hand edit to the notes file lasts until the release text itself changes', async () => {
const handEdited = served().replace('Better.', 'Better. (Edited here.)');
assert.deepEqual((await planApp({ ...app(), notes: handEdited }, rel('v1.0.0'), io())).writes, []);
const plan = await planApp({ ...app(), notes: handEdited }, { ...rel('v1.0.0'), body: 'Rewritten.' }, io());
assert.deepEqual(plan.writes.map(([p]) => p), ['releases/x.md']);
});

test('a notes file from before fingerprints is compared by its text', async () => {
const old = served().replace(/^source: .*\n/m, '');
assert.deepEqual((await planApp({ ...app(), notes: old }, rel('v1.0.0'), io())).writes, []);
assert.deepEqual((await planApp({ ...app(), notes: old }, { ...rel('v1.0.0'), body: 'Changed.' }, io())).writes.map(([p]) => p), ['releases/x.md']);
});

test('notes edited down to nothing keep the page notes it has, with a warning', async () => {
const plan = await planApp(app(), { ...rel('v1.0.0'), body: '' }, io());
assert.deepEqual(plan.writes, []);
assert.match(plan.warning!, /keeps the ones it has/);
// The sync keeps an Issue open for it, instead of one warning line an hour nobody reads.
assert.match(plan.notes!.held!, /nothing the site can show/);
});

test("a tag written v1.0 still writes the site's own version, 1.0.0, which the build checks", async () => {
const plan = await planApp(app(), { ...rel('v1.0'), body: 'Shorter tag.' }, io());
assert.match(String(plan.writes[0][1]), /^version: '1\.0\.0'$/m);
});

test('notes with a phrase the site refuses: a new version stops, an edit keeps the page notes', async () => {
await assert.rejects(planApp(app(), { ...rel(), body: 'A seamless update.' }, io()), /does not allow/);
const plan = await planApp(app(), { ...rel('v1.0.0'), body: 'It is free forever.' }, io());
assert.deepEqual(plan.writes, []);
assert.match(plan.warning!, /keeps the ones it has/);
assert.match(plan.notes!.held!, /stays free/);
});

test('a release with no APK is a warning, not a failure, and writes nothing', async () => {
const plan = await planApp(app(), rel('v1.1.0', []), io());
assert.match(plan.warning, /no APK/);
Expand Down
15 changes: 14 additions & 1 deletion tools/sync-apps.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@
* ordinary prose goes straight on, and a change to a protected section or a number waits for
* approval. With --issues, a held or refused listing keeps one GitHub Issue open saying why;
* a listing is approved by naming the id that Issue gives (--approve, or APPROVE_LISTING).
* Also with --issues, an edit to a release's notes that the site refuses keeps one Issue open
* (notes-<slug>) until the page can show the release's notes.
*
* Exits 1 if any app's release failed; the apps that succeeded are still written. A listing
* that cannot go on does not fail the run: the page keeps its text and the Issue says why.
Expand Down Expand Up @@ -132,7 +134,7 @@ try {
if (!source) continue;
try {
const rel = await (await get(`https://api.github.com/repos/${source}/releases/latest`)).json();
const app = { slug, md, readme: readFileSync(at('README.md'), 'utf8'), notesExists: existsSync(at(`releases/${slug}.md`)) };
const app = { slug, md, readme: readFileSync(at('README.md'), 'utf8'), notes: existsSync(at(`releases/${slug}.md`)) ? readFileSync(at(`releases/${slug}.md`), 'utf8') : null };
const plan = await planApp(app, rel, io(releaseField(md, 'apk')));
if (plan.warning) console.log(`::warning::${slug}: ${plan.warning}`);
if (plan.log) console.log(`${slug}: ${plan.log}`);
Expand All @@ -141,6 +143,17 @@ try {
writeFileSync(at(path), data);
}
if (plan.change) changes.push(plan.change);
// An edit to a release's notes that the site refused is otherwise one log line in a
// green run, every hour. One Issue says it until the notes are fixed or a release comes.
if (plan.notes) {
const key = `notes-${slug}`;
if (plan.notes.held) {
await report(key, (b) => b.raise(key, `${slug}: edited release notes were not published`,
`The notes of ${rel.tag_name} in ${source} were edited, and the page still shows the earlier ones, because the release's ${plan.notes.held}.\n\nReword the GitHub Release (${rel.html_url}). This Issue closes by itself within the hour once the page can show it.`));
} else {
await report(key, (b) => b.clear(key, 'The page shows the release\'s notes again.'));
}
}
} catch (e) {
failures.push(slug);
console.error(`::error::${slug}: ${e.message}`);
Expand Down
52 changes: 43 additions & 9 deletions tools/sync-lib.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@
* Like check-downloads.mjs, this reads and writes the `release:` block by pattern rather than
* with a YAML library, so the hourly job runs on a bare checkout with nothing installed. */
// Node's own type stripping reads this; release.ts imports nothing but node: modules.
import { createHash } from 'node:crypto';
import { manifestIcons, webDir } from '../src/release.ts';
import { blockedPhrases } from './format-lib.mjs';

/** The `release:` block's indented lines, or '' if there is none. */
export const releaseBlock = (md) => md.match(/^release:\n((?:[ \t]+.*\n)+)/m)?.[1] ?? '';
Expand Down Expand Up @@ -93,15 +95,24 @@ export function cleanNotes(body) {
.join('\n\n');
}

/* Which GitHub notes a releases/<slug>.md was written from: the first 12 hex of the cleaned
* text's SHA-256. When the release's notes are edited, the fingerprint stops matching and
* the sync writes the file again. An edit made to the file by hand leaves it alone, so the
* hand edit lasts until the release's own text changes. */
export const notesSource = (text) => createHash('sha256').update(text).digest('hex').slice(0, 12);
const storedSource = (file) => file?.match(/^source: ([0-9a-f]{12})$/m)?.[1];
const notesBody = (file) => (file ?? '').split(/^---$/m).slice(2).join('---').trim();

/** The file releases/<slug>.md: the notes for one version, as the page shows them. */
export function notesFile({ version, date, url, notes }) {
return [
'---',
'# Written by tools/sync-apps.mjs from the GitHub Release. Edit it if you like; the next',
'# release replaces it.',
'# Written by tools/sync-apps.mjs from the GitHub Release. Edit it if you like; it is',
'# written again when the release\'s notes change, or when the next release arrives.',
`version: '${version}'`,
`date: ${date}`,
`url: ${url}`,
`source: ${notesSource(notes)}`,
'---',
'',
notes,
Expand Down Expand Up @@ -152,12 +163,14 @@ export function apkRefusal(got, { tag, version, signer, had }) {
* this returns. An app that fails halfway therefore leaves nothing behind for the commit
* step to pick up.
*
* app { slug, md, readme, notesExists }
* app { slug, md, readme, notes } notes: releases/<slug>.md as it is now, or null
* rel the GitHub API's release JSON
* io { download(url) → Buffer, inspect(buf) → { versionName, signers, permissions },
* current() → { permissions } of the APK served now, unpack(buf) → [[path, Buffer]] }
*
* Returns { change?, warning?, writes: [[repoPath, string|Buffer]] }. */
* Returns { change?, warning?, writes: [[repoPath, string|Buffer]], notes? }. `notes` is set
* only for the version already served: { held: why } when an edit to the release's notes was
* refused, or { held: null } when the page's notes are what the release says. */
export async function planApp(app, rel, io) {
const { slug, readme } = app;
let md = app.md;
Expand All @@ -167,20 +180,41 @@ export async function planApp(app, rel, io) {
// build runs. Empty notes written here would leave main red until someone wrote them, so
// they stop the sync instead: nothing is written, the app stays where it was, and the
// hourly run says why.
const notes = () => {
// Phrases npm run check refuses would fail every hourly candidate, holding back the other
// apps too, so they stop this app here instead.
const banned = (text) => blockedPhrases(text);
const notes = (version = latest) => {
const text = cleanNotes(rel.body);
if (!text) {
throw new Error(`${rel.tag_name} has no release notes the site can show — write what changed in the GitHub Release`);
}
return notesFile({ version: latest, date: kstDate(rel.published_at), url: rel.html_url, notes: text });
const why = banned(text);
if (why.length) throw new Error(`${rel.tag_name}'s notes say what the site does not allow: ${why.join('; ')} — reword the GitHub Release`);
return notesFile({ version, date: kstDate(rel.published_at), url: rel.html_url, notes: text });
};
const cmp = compareVersions(latest, current);

if (cmp < 0) return { writes: [], log: `${current} is current (latest release ${rel.tag_name} is older)` };
if (cmp === 0) {
return app.notesExists
? { writes: [], log: `${current} is current` }
: { writes: [[`releases/${slug}.md`, notes()]], change: `${slug}: release notes for ${current}`, log: 'wrote its release notes' };
// `current`, not the tag: v1.0 and 1.0.0 compare equal, and the build wants the version
// apps/<slug>.md has.
if (app.notes == null) {
return { writes: [[`releases/${slug}.md`, notes(current)]], change: `${slug}: release notes for ${current}`, log: 'wrote its release notes' };
}
// The release's notes were edited after it came out. Notes that now clean down to
// nothing do not replace good ones: the page keeps what it has and the run says why.
const text = cleanNotes(rel.body);
const held = (why) => ({ writes: [], warning: `${rel.tag_name}'s ${why}, so the page keeps the ones it has`, notes: { held: why } });
if (!text) return held('notes now have nothing the site can show');
const why = banned(text);
if (why.length) return held(`edited notes say what the site does not allow (${why.join('; ')})`);
const stored = storedSource(app.notes);
// A file written before fingerprints has none to compare, so its text is compared: the
// same text gets left alone, different text is taken as an edited release.
const same = stored ? stored === notesSource(text) : notesBody(app.notes) === text;
if (same) return { writes: [], log: `${current} is current`, notes: { held: null } };
return { writes: [[`releases/${slug}.md`, notes(current)]], change: `${slug}: release notes for ${current} updated`, log: 'its release notes changed on GitHub, so they were written again' };
// No `notes` here: an Issue closes on the next run, once the rewrite is tested and live.
}

// A notice tied to the old version would fail the build. It was written by a person
Expand Down
Loading