diff --git a/CHANGELOG.md b/CHANGELOG.md index c493681..baebba6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/releases/README.md b/releases/README.md index 5b930cf..c4add7e 100644 --- a/releases/README.md +++ b/releases/README.md @@ -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/.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, @@ -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. diff --git a/tests/sync.test.ts b/tests/sync.test.ts index 3cf4e56..17a8569 100644 --- a/tests/sync.test.ts +++ b/tests/sync.test.ts @@ -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 @@ -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, @@ -134,7 +135,7 @@ 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 () => { @@ -142,6 +143,59 @@ test('the same or an older release changes nothing', async () => { 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/); diff --git a/tools/sync-apps.mjs b/tools/sync-apps.mjs index 6e446f6..88cebef 100644 --- a/tools/sync-apps.mjs +++ b/tools/sync-apps.mjs @@ -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-) 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. @@ -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}`); @@ -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}`); diff --git a/tools/sync-lib.mjs b/tools/sync-lib.mjs index a912c7d..d9bae18 100644 --- a/tools/sync-lib.mjs +++ b/tools/sync-lib.mjs @@ -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] ?? ''; @@ -93,15 +95,24 @@ export function cleanNotes(body) { .join('\n\n'); } +/* Which GitHub notes a releases/.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/.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, @@ -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/.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; @@ -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/.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