diff --git a/.github/workflows/weekly-release.yml b/.github/workflows/weekly-release.yml index 3c9ea8756..534e5862d 100644 --- a/.github/workflows/weekly-release.yml +++ b/.github/workflows/weekly-release.yml @@ -55,6 +55,7 @@ on: paths: - '.github/workflows/weekly-release.yml' - 'crew/scripts/release-cut.ts' + - 'crew/scripts/release-notes.ts' - 'crew/scripts/release-cadence.ts' - 'lib/changelog-fragments.ts' diff --git a/changelog.d/README.md b/changelog.d/README.md index 177f3258d..b74d7ab97 100644 --- a/changelog.d/README.md +++ b/changelog.d/README.md @@ -1,3 +1,3 @@ # CHANGELOG fragments -A PR adds its CHANGELOG entry here as `changelog.d/.md`: the entry text only, with no `## [x]` heading, and `bump: minor` or `bump: major` front matter only when the change warrants more than a patch, and `important: security|regression|data-loss|blocker` only when it must reach stable within about a day (docs/releases.md#the-daily-check). It never edits VERSION, `package.json`'s version or a released CHANGELOG section. The merge step (`gstack-ship-queue land`, or `train land` in a stamped train) assigns the version (under `merge: direct`, the release PR from `gstack-release-stamp open` does), folds every fragment into one CHANGELOG section and deletes the files. This README is skipped. See docs/ship-policy.md#changelog-fragments. +A PR adds its CHANGELOG entry here as `changelog.d/.md`: the entry text only, with no `## [x]` heading, and `bump: minor` or `bump: major` front matter only when the change warrants more than a patch, and `important: security|regression|data-loss|blocker` only when it must reach stable within about a day (docs/releases.md#the-daily-check). It never edits VERSION, `package.json`'s version or a released CHANGELOG section. The merge step (`gstack-ship-queue land`, or `train land` in a stamped train) assigns the version (under `merge: direct`, the release PR from `gstack-release-stamp open` does), folds every fragment into one CHANGELOG section and deletes the files. The entry's first sentence (or bold lead) becomes its line in the GitHub release notes, so write it for someone using gstack: docs/releases.md#release-notes. This README is skipped. See docs/ship-policy.md#changelog-fragments. diff --git a/changelog.d/release-notes-list-every-change.md b/changelog.d/release-notes-list-every-change.md new file mode 100644 index 000000000..0f312b473 --- /dev/null +++ b/changelog.d/release-notes-list-every-change.md @@ -0,0 +1 @@ +- **GitHub release notes now list every change in plain words, with a link to its pull request.** Releases v1.99.1.0 to v1.99.4.0 said only "see CHANGELOG.md", because the release cut took one headline per version and found none in entries written as bullets. Each release page now lists every change the release ships under What's new, Fixes and Changes for maintainers, one line each, with the pull request that made it, then the compare link. A release whose CHANGELOG has no entry for its version, or an entry with nothing in it, now stops with `NOTES_MISSING` instead of publishing an empty page, and notes too long for GitHub keep the changes that fit and say how many more are in the full changelog (docs/releases.md#release-notes). diff --git a/crew/docs/recommended-harness.md b/crew/docs/recommended-harness.md index c484e7282..210d65409 100644 --- a/crew/docs/recommended-harness.md +++ b/crew/docs/recommended-harness.md @@ -239,8 +239,9 @@ moves `stable` more than once in 72 hours otherwise, except for a verified security or regression fix (`--security` or `--regression`, with `--ref`): it takes the newest green commit on main's first-parent history (its required check succeeded, the backstop check succeeded, every check run completed and none failed, no active freeze), tags it `v`, publishes a -GitHub Release whose notes are one line per CHANGELOG version since the -previous release, and fast-forwards `stable`. New installs and team-mode installs +GitHub Release whose notes list every change in the CHANGELOG versions since +the previous release, one line each with the pull request that made it +([release notes](../../docs/releases.md#release-notes)), and fast-forwards `stable`. New installs and team-mode installs follow `stable`; `gstack-config set update_channel main` follows every merge. A hotfix is `--ref `, held by the same floor. Details, the floor's refusal codes and the "nothing green in the window" failure mode: diff --git a/crew/scripts/release-cut.ts b/crew/scripts/release-cut.ts index 54feb4d0d..f78c3b57c 100755 --- a/crew/scripts/release-cut.ts +++ b/crew/scripts/release-cut.ts @@ -1,7 +1,7 @@ #!/usr/bin/env -S bun --no-env-file --config=/dev/null /** * release-cut: tag the newest green commit on main as v, publish a - * GitHub Release whose notes are that span's CHANGELOG headlines, and + * GitHub Release whose notes list that span's CHANGELOG changes (release-notes.ts), and * fast-forward refs/heads/stable to it (docs/releases.md). Run by * .github/workflows/weekly-release.yml ("Stable release") every day at 14:00 * UTC with --daily (the daily check, crew/scripts/release-cadence.ts: an important @@ -69,10 +69,12 @@ import * as os from 'node:os'; import * as path from 'node:path'; import { spawnSync } from 'node:child_process'; import { FLOOR_HOURS, IMPORTANT_FLOOR_HOURS, SCHEDULED_GRACE_HOURS, decideDaily, importantChanges, type DailyDecision } from './release-cadence'; +import { KIND_LABEL, NOTES_CAP, changeSources, changelogEntries, compareVersions, releaseKind, releaseNotes } from './release-notes'; import { bucketClass } from '../../lib/ci-gate'; import { headCheckRows, type AsideRuns } from '../../lib/ci-head-checks'; export { FLOOR_HOURS, SCHEDULED_GRACE_HOURS }; +export { NOTES_CAP, changelogEntries, compareVersions, releaseKind, releaseNotes }; export type Gh = (args: string[]) => { status: number | null; stdout: string; stderr: string }; export type Git = (args: string[]) => { ok: boolean; out: string }; @@ -87,7 +89,6 @@ const NOTES_LOCAL = 'refs/notes/gstack-trains-release'; const RED = new Set(['failure', 'timed_out', 'cancelled', 'action_required', 'startup_failure', 'stale']); export const WINDOW_DAYS = 7; export const WINDOW_COMMITS = 200; -export const NOTES_CAP = 60_000; const HOUR = 3_600_000; export const runGh: Gh = (args) => { @@ -104,16 +105,6 @@ function parseJson(r: { status: number | null; stdout: string }): T | null { try { return JSON.parse(r.stdout) as T; } catch { return null; } } -/** Four-part versions compare numerically, part by part. */ -export function compareVersions(a: string, b: string): number { - const pa = a.split('.').map(Number), pb = b.split('.').map(Number); - for (let i = 0; i < Math.max(pa.length, pb.length); i++) { - const d = (pa[i] ?? 0) - (pb[i] ?? 0); - if (d !== 0) return d; - } - return 0; -} - /** Green names what gated the commit: the backstop check's name, or `train `. Pending means a check run on it is still going. */ export type Verdict = { green: true; via: string } | { green: false; why: string; pending: boolean }; interface CheckRun { id?: number; name: string; status: string; conclusion: string | null } @@ -231,68 +222,9 @@ export function readTrainNotes(git: Git, notesRef = NOTES_REF): TrainNotes { return notes; } -export interface ChangelogEntry { version: string; date: string; headline: string } - -/** Every "## [X.Y.Z.W] - date" entry of a CHANGELOG with its first prose line, markdown stripped. */ -export function changelogEntries(text: string): ChangelogEntry[] { - const out: ChangelogEntry[] = []; - const lines = text.split('\n'); - for (let i = 0; i < lines.length; i++) { - const m = /^## \[(\d+(?:\.\d+)+)\](?: - (\S+))?/.exec(lines[i]!); - if (!m) continue; - let headline = ''; - for (let j = i + 1; j < lines.length && !lines[j]!.startsWith('## '); j++) { - const l = lines[j]!.trim(); - if (!l || l.startsWith('#') || l.startsWith('|') || l.startsWith('-') || l.startsWith('```')) continue; - const bold = /^\*\*(.+?)\*\*/.exec(l); - headline = (bold ? bold[1]! : l.replace(/\*\*/g, '')).replace(/\s+/g, ' '); - break; - } - out.push({ version: m[1]!, date: m[2] ?? '', headline }); - } - return out; -} - -export interface NotesInput { repo: string; version: string; date: string; prevVersion: string | null; prevTag: string | null; entries: ChangelogEntry[]; hotfix: boolean; first?: boolean; exception?: Exception | null } - /** A verified floor exception (a security or a regression cut): the sanitized reason and what tied it to the released commits. */ export interface Exception { kind: 'security' | 'regression'; reason: string; evidence: string } -const KIND_LABEL = { security: 'Security', regression: 'Regression' } as const; - -export function releaseKind(hotfix: boolean, exception: Exception | null | undefined): 'security' | 'regression' | 'hotfix' | 'regular' { - return exception ? exception.kind : hotfix ? 'hotfix' : 'regular'; -} - -/** Release notes: one headline per version in (prev, version], capped at NOTES_CAP. */ -export function releaseNotes(n: NotesInput): string { - const span = n.entries.filter(e => compareVersions(e.version, n.version) <= 0 && (!n.prevVersion || compareVersions(e.version, n.prevVersion) > 0)) - .sort((a, b) => compareVersions(b.version, a.version)); - const plural = span.length === 1 ? '' : 's'; - const changelogUrl = 'https://github.com/' + n.repo + '/blob/v' + n.version + '/CHANGELOG.md'; - const compare = n.prevTag ? '[Compare](https://github.com/' + n.repo + '/compare/' + n.prevTag + '...v' + n.version + ') or read ' : 'Read '; - const head = [ - '## gstack v' + n.version + ' (' + releaseKind(n.hotfix, n.exception) + ' release)', - '', - ...(n.exception ? ['**' + KIND_LABEL[n.exception.kind] + ' release:** `' + n.exception.reason + '` (verified: ' + n.exception.evidence + '). Every version since the previous release ships with it.', ''] : []), - n.first || !n.prevVersion - ? 'First tagged release: the ' + span.length + ' version' + plural + (n.prevVersion ? ' since v' + n.prevVersion + ' (the week before it)' : '') + ', one line each; the [full changelog](' + changelogUrl + ') has every earlier one.' - : span.length + ' version' + plural + ' since v' + n.prevVersion + ', one line each. ' + compare + 'the [full changelog](' + changelogUrl + ').', - '', - 'New installs and team-mode installs follow the stable branch, which now points here; gstack-config set update_channel main follows every merge instead ([docs/releases.md](https://github.com/' + n.repo + '/blob/v' + n.version + '/docs/releases.md)).', - '', - ].join('\n'); - const bullets = span.map(e => '- **' + e.version + '**' + (e.date ? ' (' + e.date + ')' : '') + ': ' + (e.headline || 'see CHANGELOG.md')); - let body = head + bullets.join('\n') + '\n'; - if (body.length > NOTES_CAP) { - const kept: string[] = []; - let size = head.length; - for (const b of bullets) { if (size + b.length + 1 > NOTES_CAP - 200) break; kept.push(b); size += b.length + 1; } - body = head + kept.join('\n') + '\n- ...and ' + (bullets.length - kept.length) + ' more versions; see CHANGELOG.md\n'; - } - return body; -} - const iso = (ms: number) => new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z'); /** @@ -448,8 +380,8 @@ export interface Plan { tagExists: 'no' | 'same' | 'other'; stableAt: boolean; notes: string; skipped: string[]; exception: Exception | null; floor: Floor; ridingAlong: number; } -export type RefusalCode = 'NOTHING_NEW' | 'NO_GREEN_COMMIT' | 'NO_RELEASE_PR' | 'REFUSED' | 'REFUSED_FLOOR' | 'FLOOR_UNKNOWN' | 'REFUSED_SECURITY' | 'REFUSED_REGRESSION'; -/** `sha` names the candidate on NO_RELEASE_PR, which comes after the candidate was picked but before a plan exists. */ +export type RefusalCode = 'NOTHING_NEW' | 'NO_GREEN_COMMIT' | 'NO_RELEASE_PR' | 'NOTES_MISSING' | 'REFUSED' | 'REFUSED_FLOOR' | 'FLOOR_UNKNOWN' | 'REFUSED_SECURITY' | 'REFUSED_REGRESSION'; +/** `sha` names the candidate on NO_RELEASE_PR and NOTES_MISSING, which come after the candidate was picked but before a plan exists. */ export type PlanResult = { ok: true; plan: Plan } | { ok: false; code: RefusalCode; message: string; skipped?: string[]; next?: string; plan?: Plan; sha?: string }; export interface PlanOptions { @@ -567,9 +499,11 @@ export function planRelease(o: PlanOptions): PlanResult { } const changelog = git(['show', sha + ':CHANGELOG.md']); const date = git(['show', '-s', '--format=%cs', sha]).out; - const notes = releaseNotes({ repo, version, date, prevVersion, prevTag, entries: changelog.ok ? changelogEntries(changelog.out) : [], hotfix: Boolean(o.ref), first: !before, exception }); + const written = releaseNotes({ repo, version, date, prevVersion, prevTag, entries: changelog.ok ? changelogEntries(changelog.out) : [], hotfix: Boolean(o.ref), first: !before, exception, sources: changeSources(git, before, sha) }); + if (!written.ok) return { ok: false, code: 'NOTES_MISSING', sha, message: written.why }; + const notes = written.body; const floor = floorStatus({ git, gh, repo, prevStable, sha, exception: exception?.kind ?? null, scheduled: Boolean(o.scheduled), now: o.now?.() ?? Date.now(), floorHours: o.floorHours }); - const ridingAlong = Math.max(0, notes.split('\n').filter(l => l.startsWith('- **')).length - 1); + const ridingAlong = written.versions - 1; const plan: Plan = { sha, version, tag, date, hotfix: Boolean(o.ref), via, prevStable, prevVersion, prevTag, tagExists, stableAt: prevStable === sha, notes, skipped, exception, floor, ridingAlong }; if (floor.verdict === 'refused' || floor.verdict === 'unknown') return { ok: false, code: floor.verdict === 'refused' ? 'REFUSED_FLOOR' : 'FLOOR_UNKNOWN', message: floor.message!, next: floor.next, plan }; return { ok: true, plan }; @@ -621,7 +555,7 @@ export function describePlan(p: Plan, dryRun: boolean): string[] { 'CANDIDATE: ' + p.sha + ' (' + p.date + ')' + (p.hotfix ? ' [hotfix: --ref]' : '') + ' gated by ' + p.via, 'VERSION: ' + p.version + ' -> tag ' + p.tag + (p.tagExists === 'same' ? ' (exists at this commit)' : ''), 'STABLE: ' + (p.stableAt ? 'already at ' + p.sha.slice(0, 12) + ' (finishing an earlier cut)' : (p.prevStable ? p.prevStable.slice(0, 12) + ' (v' + (p.prevVersion ?? '?') + ')' : 'none yet') + ' -> ' + p.sha.slice(0, 12)), - 'NOTES: ' + p.notes.split('\n').filter(l => l.startsWith('- ')).length + ' version lines, ' + p.notes.length + ' chars', + 'NOTES: ' + p.notes.split('\n').filter(l => l.startsWith('- ')).length + ' change lines, ' + p.notes.length + ' chars', p.floor.line, ]; if (p.exception) lines.push(p.exception.kind.toUpperCase() + ': `' + p.exception.reason + '` (verified: ' + p.exception.evidence + ')', 'RIDING_ALONG: ' + p.ridingAlong + ' other version' + (p.ridingAlong === 1 ? '' : 's') + ' ship with the fix'); @@ -638,7 +572,7 @@ export function describePlan(p: Plan, dryRun: boolean): string[] { /** * The daily check (--daily, crew/scripts/release-cadence.ts): plan at the 24-hour important floor, then let * decideDaily pick the trigger, if any; NO_RELEASE_PR becomes a blocked decision only when a trigger - * is due. decision is null when the plan's refusal stands on its own (a freeze, nothing green, + * is due, and NOTES_MISSING stops only a cut decision (no version to cut today needs no notes). decision is null when the plan's refusal stands on its own (a freeze, nothing green, * FLOOR_UNKNOWN, a non-fast-forward, a version stamped on an unrelated commit); lines then say which * important changes are still waiting on the gate. A plan that cleared while the daily check itself * cannot date stable is held as FLOOR_UNKNOWN, so a null decision never reaches a cut. @@ -652,7 +586,7 @@ export function planDaily(o: PlanOptions & { fragmentsDir?: string }): { planned const noReleasePr = !planned.ok && planned.code === 'NO_RELEASE_PR'; const sha = planned.ok ? planned.plan.sha : planned.code === 'REFUSED_FLOOR' ? planned.plan?.sha - : noReleasePr ? planned.sha + : noReleasePr || (!planned.ok && planned.code === 'NOTES_MISSING') ? planned.sha : planned.code === 'NOTHING_NEW' ? prev ?? undefined : undefined; const moved = prev ? stableMovedAt(git, gh, repo, prev) : null; diff --git a/crew/scripts/release-notes.ts b/crew/scripts/release-notes.ts new file mode 100644 index 000000000..022005836 --- /dev/null +++ b/crew/scripts/release-notes.ts @@ -0,0 +1,224 @@ +/** + * Release notes for a cut (crew/scripts/release-cut.ts, docs/releases.md#release-notes): every change in the + * CHANGELOG versions a release ships, one line each, grouped under What's new, Fixes and Changes for + * maintainers, with a link to the pull request that made it. + * + * A change is a top-level bullet of a version's section, or a paragraph when it is not a bullet. Its line is + * the bullet's bold lead when that lead is a sentence, else its first sentence, with internal issue codes in + * parentheses dropped. Its pull request is read from git (changeSources), never from its words: the commit that + * added a version's heading folded the changelog.d fragments it deleted, in path order, so a folded version lists + * each of those fragments' changes, as the fragment read just before the fold, with the trailing "(#N)" of the + * squash commit that added that file there (wherever it sits, since a release can fold fragments that landed + * before the previous one, and never a later commit that reused the file name). Changes the version holds past + * its fragments' link the heading commit's pull request; a release commit (a "v release" subject) + * links nothing. + * Its group comes from the heading it sits under ("### Fixed", "### Added", "### Tests" and the like, read + * inside its fragment when it has one), else from the files its pull request touched (only tests, CI and + * gstack's own release tooling: maintainers), else from its words (internal shipping machinery: maintainers; + * "no longer", "again", "fix": a fix; anything else is new). A release whose own version has no entry, or a version + * with no change, refuses the notes instead of publishing a stub or an older version's entry. Notes past NOTES_CAP + * keep the changes that fit and send the rest to the full changelog. + */ +import { parseFragment } from '../../lib/changelog-fragments'; +import type { Exception, Git } from './release-cut'; + +export const NOTES_CAP = 60_000; + +export interface Change { text: string; heading: string } +export interface ChangelogEntry { version: string; date: string; changes: Change[] } +/** A folded fragment: the pull request whose commit added its file (null when that commit names none), the files that commit touched, and its changes. */ +export interface FragmentSource { pr: number | null; files: string[]; changes: Change[] } +/** The commit that added a version's heading: its pull request (null for a release commit), its files, and the fragments it folded in path order. */ +export interface VersionSource { pr: number | null; files: string[]; fragments: FragmentSource[] } +export interface NotesSources { versions: Record } +export interface NotesInput { repo: string; version: string; date: string; prevVersion: string | null; prevTag: string | null; entries: ChangelogEntry[]; hotfix: boolean; first?: boolean; exception?: Exception | null; sources?: NotesSources } +export type Notes = { ok: true; body: string; versions: number } | { ok: false; why: string }; +type Group = 'new' | 'fix' | 'maintainers'; + +const GROUPS: Array<[Group, string]> = [['new', "What's new"], ['fix', 'Fixes'], ['maintainers', 'Changes for maintainers']]; +export const KIND_LABEL = { security: 'Security', regression: 'Regression' } as const; +const HEADING_GROUP: Array<[RegExp, Group]> = [ + [/^(tests?|testing|ci|for contributors|contributors|internal|maintainers?|chores?|infrastructure)\b/i, 'maintainers'], + [/^(fixed|fixes|bug ?fixes|security)\b/i, 'fix'], + [/^(added|new|features?)\b/i, 'new'], +]; +const NEUTRAL_PATH = /^(changelog\.d\/|CHANGELOG\.md$|VERSION$|package\.json$|bun\.lock$)/; +const MAINTAINER_PATH = /^(test\/|crew\/|\.github\/|evals?\/|CONTRIBUTING\.md$|TODOS\.md$|docs\/TESTING)/; +const MAINTAINER_WORDS = /\b(test suite|flaky|CI|evals?|receipts?|pregate|ship-queue|merge trains?|carry|lander|release gate|backstop|fix-checks?|stamps?|review plan|review log)\b/i; +const FIX_WORDS = /\b(no longer|again|fix(es|ed)?|broken|regression|crash(es|ed)?|bug)\b|instead of (failing|refusing|crashing|stopping)/i; +const STAMP_SUBJECT = /^v\d+(\.\d+)+ release\b/; + +/** Four-part versions compare numerically, part by part. */ +export function compareVersions(a: string, b: string): number { + const pa = a.split('.').map(Number), pb = b.split('.').map(Number); + for (let i = 0; i < Math.max(pa.length, pb.length); i++) { + const d = (pa[i] ?? 0) - (pb[i] ?? 0); + if (d !== 0) return d; + } + return 0; +} + +/** The changes in a run of CHANGELOG lines: top-level bullets with their continuation lines, and plain paragraphs. */ +export function changesIn(lines: string[]): Change[] { + const changes: Change[] = []; + let heading = '', open: Change | null = null, blank = false, fence = false; + for (const raw of lines) { + const l = raw.trimEnd(); + if (/^\s*(```|~~~)/.test(l)) { fence = !fence; continue; } + if (fence) continue; + if (/^#{2,}\s/.test(l)) { heading = l.replace(/^#+\s*/, '').trim(); open = null; continue; } + if (!l.trim()) { blank = true; continue; } + const wasBlank = blank; + blank = false; + if (/^[-*] /.test(l)) { open = { text: l.slice(2).trim(), heading }; changes.push(open); continue; } + if (/^\s*\|/.test(l) || /^\s*<\/?(details|summary)/i.test(l)) { open = null; continue; } + if (open && (/^\s/.test(l) || !wasBlank)) { open.text += ' ' + l.trim(); continue; } + open = { text: l.trim(), heading }; + changes.push(open); + } + return changes; +} + +/** Every "## [X.Y.Z.W] - date" section of a CHANGELOG with its changes. */ +export function changelogEntries(text: string): ChangelogEntry[] { + const out: ChangelogEntry[] = []; + const lines = text.split('\n'); + for (let i = 0; i < lines.length; i++) { + const m = /^## \[(\d+(?:\.\d+)+)\](?: - (\S+))?/.exec(lines[i]!); + if (!m) continue; + let j = i + 1; + while (j < lines.length && !lines[j]!.startsWith('## [')) j++; + out.push({ version: m[1]!, date: m[2] ?? '', changes: changesIn(lines.slice(i + 1, j)) }); + i = j - 1; + } + return out; +} + +function firstSentence(text: string): string { + let code = false; + for (let i = 0; i < text.length; i++) { + const c = text[i]!; + if (c === '`') code = !code; + if (code || !'.!?'.includes(c)) continue; + const rest = text.slice(i + 1); + if (/^["')*]*$/.test(rest) || /^["')*]*\s+["'(\[*`]*[A-Z0-9/@`]/.test(rest)) return text.slice(0, i + 1) + (/^["')*]+/.exec(rest)?.[0] ?? ''); + } + return text; +} + +/** One line for a change: its bold lead when that is a sentence, else its first sentence, markdown bold and internal codes removed. */ +export function changeLine(text: string): string { + const bold = /^\*\*(.+?)\*\*/.exec(text); + const lead = bold && /[.!?]["')`]*$/.test(bold[1]!.trim()) ? bold[1]! : firstSentence(text); + return lead.replace(/\*\*/g, '') + .replace(/\s*\((?!CVE-|GHSA-)[A-Z][A-Z0-9]*-\d+(?:(?:,\s*|\s+and\s+)(?!CVE-|GHSA-)[A-Z][A-Z0-9]*-\d+)*\)/g, '') + .replace(/\b([Oo])utside voice/g, (_, o: string) => (o === 'O' ? 'S' : 's') + 'econd-model review') + .replace(/\s+/g, ' ').replace(/\s+([.,;:!?])/g, '$1').trim(); +} + +function prOf(subject: string): number | null { + const squash = /\(#(\d+)\)\s*$/.exec(subject); + const merge = /^Merge pull request #(\d+)/.exec(subject); + return squash ? Number(squash[1]) : merge ? Number(merge[1]) : null; +} + +/** + * The pull requests behind the versions whose headings were added in from..to along main's first-parent history: for + * each, the commit that added its "## [version]" heading and the changelog.d fragments that commit deleted, each read + * as it stood just before that commit, with the pull request of the commit that added that file. No from (a first + * release) reads nothing. + */ +export function changeSources(git: Git, from: string | null, to: string): NotesSources { + const out: NotesSources = { versions: {} }; + if (!from) return out; + const range = ['--first-parent', '--diff-merges=first-parent', '--no-renames', from + '..' + to]; + const log = git(['log', '--format=%x00%H%x09%s', '--name-status', ...range]); + if (!log.ok) return out; + const commits = new Map(); + for (const block of log.out.split('\0').filter(b => b.trim())) { + const [head, ...rest] = block.split('\n'); + const [sha, subject = ''] = head!.split('\t'); + const status = rest.filter(l => l.trim()).map(l => l.split('\t')); + const folded = status.filter(([kind, file]) => kind === 'D' && /^changelog\.d\/[^/]+\.md$/.test(file!) && file !== 'changelog.d/README.md').map(([, file]) => file!).sort(); + commits.set(sha!, { pr: prOf(subject), stamp: STAMP_SUBJECT.test(subject), files: status.map(s => s.at(-1)!), folded }); + } + const fragment = (fold: string, file: string): FragmentSource | null => { + const added = git(['log', '-1', '--no-patch', '--first-parent', '--diff-merges=first-parent', '--diff-filter=A', '--format=%H%x09%s', fold + '^', '--', file]); + const [sha, subject = ''] = added.ok ? added.out.split('\t') : []; + const shown = git(['show', fold + '^:' + file]); + const parsed = shown.ok ? parseFragment(file, shown.out) : null; + if (!parsed || !('body' in parsed)) return null; + const files = sha ? git(['show', '--diff-merges=first-parent', '--no-renames', '--format=', '--name-only', sha]) : null; + return { pr: sha ? prOf(subject) : null, files: files?.ok ? files.out.split('\n').filter(Boolean) : [], changes: changesIn(parsed.body.split('\n')) }; + }; + const headings = git(['log', '--format=%x00%H', '-p', '--unified=0', ...range, '--', 'CHANGELOG.md']); + if (headings.ok) for (const block of headings.out.split('\0').filter(b => b.trim())) { + const sha = block.slice(0, 40); + const c = commits.get(sha); + if (!c) continue; + for (const m of block.matchAll(/^\+## \[(\d+(?:\.\d+)+)\]/gm)) { + out.versions[m[1]!] = { pr: c.stamp ? null : c.pr, files: c.files, fragments: c.folded.map(file => fragment(sha, file)).filter((f): f is FragmentSource => f !== null) }; + } + } + return out; +} + +function groupOf(line: string, heading: string, files: string[]): Group { + const byHeading = HEADING_GROUP.find(([re]) => re.test(heading)); + if (byHeading) return byHeading[1]; + const own = files.filter(f => !NEUTRAL_PATH.test(f)); + if (own.length && own.every(f => MAINTAINER_PATH.test(f))) return 'maintainers'; + if (MAINTAINER_WORDS.test(line)) return 'maintainers'; + return FIX_WORDS.test(line) ? 'fix' : 'new'; +} + +export function releaseKind(hotfix: boolean, exception: Exception | null | undefined): 'security' | 'regression' | 'hotfix' | 'regular' { + return exception ? exception.kind : hotfix ? 'hotfix' : 'regular'; +} + +/** The release notes for versions in (prevVersion, version], or why there are none to publish. */ +export function releaseNotes(n: NotesInput): Notes { + const span = n.entries.filter(e => compareVersions(e.version, n.version) <= 0 && (!n.prevVersion || compareVersions(e.version, n.prevVersion) > 0)) + .sort((a, b) => compareVersions(b.version, a.version)); + if (!span.length) return { ok: false, why: 'CHANGELOG.md at the release has no entry for v' + n.version + (n.prevVersion ? ' or any version since v' + n.prevVersion : '') }; + if (compareVersions(span[0]!.version, n.version) !== 0) return { ok: false, why: 'CHANGELOG.md at the release has no entry for v' + n.version + ', only for the older v' + span[0]!.version + '; write the entry before cutting the release' }; + const grouped: Record = { new: [], fix: [], maintainers: [] }; + const empty: string[] = []; + for (const e of span) { + const version = n.sources?.versions[e.version]; + const folded = version?.fragments ?? []; + const own = e.changes.slice(folded.reduce((count, f) => count + f.changes.length, 0)); + const items: Array<{ change: Change; from?: { pr: number | null; files: string[] } }> = [...folded.flatMap(f => f.changes.map(change => ({ change, from: f }))), ...own.map(change => ({ change, from: version }))]; + let lines = 0; + for (const { change, from } of items) { + const line = changeLine(change.text); + if (!line) continue; + const pr = from?.pr ? ' ([#' + from.pr + '](https://github.com/' + n.repo + '/pull/' + from.pr + '))' : ''; + grouped[groupOf(line, change.heading, from?.files ?? [])].push('- ' + line + pr); + lines++; + } + if (!lines) empty.push('v' + e.version); + } + if (empty.length) return { ok: false, why: 'no change to list in the CHANGELOG entry of ' + empty.join(', ') + '; write the entry before cutting the release' }; + const kind = releaseKind(n.hotfix, n.exception); + const changelogUrl = 'https://github.com/' + n.repo + '/blob/v' + n.version + '/CHANGELOG.md'; + const plural = span.length === 1 ? '' : 's'; + const render = (omitted: number) => [ + '## gstack v' + n.version + (kind === 'regular' ? '' : ' (' + kind + ' release)'), + '', + ...(n.exception ? ['**' + KIND_LABEL[n.exception.kind] + ' release:** `' + n.exception.reason + '` (verified: ' + n.exception.evidence + '). Every version since the previous release ships with it.', ''] : []), + ...(n.first || !n.prevVersion ? ['First tagged release: the ' + span.length + ' version' + plural + (n.prevVersion ? ' since v' + n.prevVersion : '') + '; the [full changelog](' + changelogUrl + ') has every earlier one.', ''] : []), + ...GROUPS.filter(([g]) => grouped[g].length).flatMap(([g, title]) => ['### ' + title, '', ...grouped[g], '']), + ...(omitted ? [omitted + (omitted === 1 ? ' more change is' : ' more changes are') + ' in the [full changelog](' + changelogUrl + ').', ''] : []), + (n.prevTag ? '[Compare ' + n.prevTag + '...v' + n.version + '](https://github.com/' + n.repo + '/compare/' + n.prevTag + '...v' + n.version + ') · ' : '') + '[Full changelog](' + changelogUrl + ')', + '', + ].join('\n'); + let omitted = 0, body = render(0); + for (const g of [...GROUPS].reverse().map(([g]) => g)) { + while (body.length > NOTES_CAP && grouped[g].length) { + grouped[g].pop(); + body = render(++omitted); + } + } + return { ok: true, body, versions: span.length }; +} diff --git a/crew/test/release-cadence.test.ts b/crew/test/release-cadence.test.ts index 6988b80ab..e05cb850d 100644 --- a/crew/test/release-cadence.test.ts +++ b/crew/test/release-cadence.test.ts @@ -185,7 +185,7 @@ describe('planDaily', () => { expect(blocked.decision?.lines[0]).toStartWith('NO_RELEASE_PR: important change waiting, no release PR'); expect(blocked.planned.ok).toBe(false); - const stamped = r.commit('release 1.0.1', { VERSION: '1.0.1\n', 'changelog.d/fix.md': null }); + const stamped = r.commit('release 1.0.1', { VERSION: '1.0.1\n', 'CHANGELOG.md': '# Changelog\n\n## [1.0.1] - 2026-11-02\n\n- **The fix.**\n\n## [1.0.0] - 2026-11-01\n\n**First.**\n', 'changelog.d/fix.md': null }); r.refresh(); const cut = day(25); expect(cut.decision).toMatchObject({ action: 'cut', trigger: 'important' }); @@ -217,7 +217,7 @@ describe('planDaily', () => { // seam=gh faked (only the last release view fails), git real; no_claim=which gh errors are transient test('a plan that clears while the daily check cannot date stable is FLOOR_UNKNOWN, never a cuttable plan with no decision', () => { const r = repo(); - r.commit('release 1.0.1', { VERSION: '1.0.1\n' }); + r.commit('release 1.0.1', { VERSION: '1.0.1\n', 'CHANGELOG.md': '# Changelog\n\n## [1.0.1] - 2026-11-02\n\n- **The fix.**\n\n## [1.0.0] - 2026-11-01\n\n**First.**\n' }); r.refresh(); const g = gitIn(r.work); const green = fakeGh(); @@ -278,7 +278,7 @@ describe.skipIf(process.platform === 'win32')('release-cut --daily (the workflow expect(plainCut.status).toBe(1); expect(plainCut.stdout).toContain('::error title=release-cut NO_RELEASE_PR::'); - const stamped = r.commit('release 1.0.1', { VERSION: '1.0.1\n', 'changelog.d/fix.md': null, 'changelog.d/docs.md': null }); + const stamped = r.commit('release 1.0.1', { VERSION: '1.0.1\n', 'CHANGELOG.md': '# Changelog\n\n## [1.0.1] - 2026-11-02\n\n- **The fix.**\n\n## [1.0.0] - 2026-11-01\n\n**First.**\n', 'changelog.d/fix.md': null, 'changelog.d/docs.md': null }); r.refresh(); const due = run('--daily', '--dry-run'); expect(due.status, due.stdout + due.stderr).toBe(0); @@ -299,4 +299,34 @@ describe.skipIf(process.platform === 'win32')('release-cut --daily (the workflow expect(ref.status).toBe(2); expect(ref.stderr).toContain('--daily picks its own candidate'); }); + + // Value: protects=no version to cut today needs no notes: a stamped version whose CHANGELOG lacks its entry leaves a day with no due trigger green, + // and only a due cut refuses NOTES_MISSING; fails_when=the daily check goes red on a quiet day because the notes were built before the decision, or a + // due cut publishes without notes; why_new=planDaily dropped the candidate on NOTES_MISSING, so no decision ran; seam=gh shim on PATH, real bare origin; + // no_claim=GitHub's API or a real gh + test('a version with no CHANGELOG entry stays green on a day with no due trigger and refuses NOTES_MISSING only when a cut is due', () => { + const r = repo(30); + const shim = path.join(r.root, 'shim'); + fs.mkdirSync(shim); + fs.writeFileSync(path.join(shim, 'gh'), '#!/usr/bin/env bash\ncase "$*" in\n' + ciShimCases(GREEN) + ' "release view v1.0.0 "*) echo \'{}\' ;;\n *) exit 1 ;;\nesac\n', { mode: 0o755 }); + const env: Record = { ...process.env, PATH: shim + path.delimiter + process.env.PATH, GITHUB_ACTIONS: 'true' }; + for (const k of ['GITHUB_EVENT_NAME', 'GITHUB_STEP_SUMMARY']) delete env[k]; + const run = () => spawnSync(process.execPath, [...bunIsolationArgs(), 'run', path.join(path.resolve(import.meta.dir, '..', '..'), 'crew', 'scripts', 'release-cut.ts'), '--repo', 'o/r', '--daily'], + { cwd: r.work, encoding: 'utf8', timeout: 60_000, env }); + + r.commit('release 1.0.1', { VERSION: '1.0.1\n' }); + r.refresh(); + const quiet = run(); + expect(quiet.status, quiet.stdout + quiet.stderr).toBe(0); + expect(quiet.stdout.split('\n')[0]).toStartWith('DAILY: no-op: nothing important since stable'); + expect(quiet.stdout).not.toContain('NOTES_MISSING'); + + r.commit('fix the tar path (#4101)', { 'changelog.d/fix.md': '---\nimportant: security\n---\n- tar\n' }); + r.refresh(); + const due = run(); + expect(due.status, due.stdout + due.stderr).toBe(1); + expect(due.stdout.split('\n')[0]).toStartWith('DAILY: cut (important: security in #4101'); + expect(due.stdout).toContain('NOTES_MISSING: CHANGELOG.md at the release has no entry for v1.0.1'); + expect(due.stdout).toContain('::error title=release-cut NOTES_MISSING::'); + }); }); diff --git a/crew/test/release-cut.test.ts b/crew/test/release-cut.test.ts index 98eb76786..d809e48f9 100644 --- a/crew/test/release-cut.test.ts +++ b/crew/test/release-cut.test.ts @@ -17,6 +17,7 @@ import { BACKSTOP_CHECK, CUT_WORKFLOW, FLOOR_HOURS, NEVER_GATING_WORKFLOWS, NOTES_CAP, NOTES_REF, REQUIRED_CHECK, SCHEDULED_GRACE_HOURS, changelogEntries, compareVersions, cutRelease, describePlan, floorStatus, gateVerdict, gitIn, planRelease, readTrainNotes, releaseNotes, sanitizeReason, stableMovedAt, verifyRegression, verifySecurity, type Gh, type Git, type TrainEvidence, } from '../scripts/release-cut'; +import { changeLine, changeSources, changesIn, type NotesSources } from '../scripts/release-notes'; const bases: string[] = []; // A cut made a moment ago clears the 72-hour floor at this clock. @@ -128,10 +129,11 @@ describe('release-cut: planning', () => { f.shas['1.0.3']!.slice(0, 12) + ': ' + BACKSTOP_CHECK + ' is still running', f.shas['1.0.2']!.slice(0, 12) + ': red check runs: windows-free-tests', ]); - expect(r.plan.notes).toContain('First tagged release: the 2 versions, one line each'); - expect(r.plan.notes).toContain('- **1.0.1** (2026-10-21): Second: the updater no longer skips.'); - expect(r.plan.notes).toContain('- **1.0.0**'); - expect(r.plan.notes).not.toContain('1.0.2'); + expect(r.plan.notes).toContain('First tagged release: the 2 versions;'); + expect(r.plan.notes).toContain('- Second: the updater no longer skips.'); + expect(r.plan.notes).toContain('- First one.'); + expect(r.plan.notes).not.toContain('Third fixes Windows.'); + expect(r.plan.notes).not.toContain('see CHANGELOG'); const lines = describePlan(r.plan, true); expect(lines.some(l => l.startsWith('DRY_RUN:'))).toBe(true); expect(lines).toContain(' git push --force-with-lease=refs/heads/stable: origin ' + f.shas['1.0.1'] + ':refs/heads/stable'); @@ -605,10 +607,10 @@ describe('release-cut: cutting, hotfixes and the forward-only stable', () => { expect(promo.plan.prevStable).toBe(f.shas['1.0.3']); expect(promo.plan.prevTag).toBe('v1.0.3'); expect(promo.plan.notes).toContain('## gstack v1.0.4 (hotfix release)'); - expect(promo.plan.notes).toContain('1 version since v1.0.3'); + expect(promo.plan.notes).not.toContain('First tagged release'); expect(promo.plan.notes).toContain('compare/v1.0.3...v1.0.4'); - expect(promo.plan.notes).toContain('- **1.0.4**'); - expect(promo.plan.notes).not.toContain('- **1.0.3**'); + expect(promo.plan.notes).toContain('- Hotfix: the lease never blocks.'); + expect(promo.plan.notes).not.toContain('Fourth trims the preamble.'); const cut2 = cutRelease(promo.plan, { repo: f.repo, git: f.git, gh: f.gh, notesDir: f.base }); expect(cut2.ok, cut2.lines.join('\n')).toBe(true); expect(git(f.origin, 'rev-parse', 'refs/heads/stable')).toBe(hot); @@ -643,7 +645,7 @@ describe('release-cut: cutting, hotfixes and the forward-only stable', () => { expect(again.plan.stableAt).toBe(true); expect(again.plan.tagExists).toBe('same'); expect(again.plan.prevVersion).toBeNull(); - expect(again.plan.notes).toContain('First tagged release: the 4 versions, one line each'); + expect(again.plan.notes).toContain('First tagged release: the 4 versions;'); expect(describePlan(again.plan, true)[2]).toBe('STABLE: already at ' + f.shas['1.0.3']!.slice(0, 12) + ' (finishing an earlier cut)'); } const done = cutRelease(resumed, { repo: f.repo, git: f.git, gh: f.gh, notesDir: f.base }); @@ -665,9 +667,9 @@ describe('release-cut: cutting, hotfixes and the forward-only stable', () => { if (!finish.ok) return; expect(finish.plan.sha).toBe(hot); expect(finish.plan.prevTag).toBe('v1.0.3'); - expect(finish.plan.notes).toContain('1 version since v1.0.3'); + expect(finish.plan.notes).toContain('- Hotfix: the lease never blocks.'); expect(finish.plan.notes).toContain('compare/v1.0.3...v1.0.4'); - expect(finish.plan.notes).not.toContain('- **1.0.3**'); + expect(finish.plan.notes).not.toContain('Fourth trims the preamble.'); const once = planRelease({ repo: f.repo, git: f.git, gh: f.gh }); expect(cutRelease(finish.plan, { repo: f.repo, git: f.git, gh: f.gh, notesDir: f.base }).ok).toBe(true); expect(once.ok).toBe(true); @@ -739,7 +741,7 @@ describe.skipIf(process.platform === 'win32')('release-cut: the workflow entry p const written = fs.readFileSync(summary, 'utf8'); expect(written).toContain('- CANDIDATE: ' + f.shas['1.0.3']); expect(written).toContain('
Release notes'); - expect(written).toContain('- **1.0.3** (2026-10-23): Fourth trims the preamble.'); + expect(written).toContain('- Fourth trims the preamble.'); expect(execFileSync('git', ['ls-remote', f.origin, 'refs/heads/stable', 'refs/tags/v1.0.3'], { encoding: 'utf8', timeout: 30_000 }).trim()).toBe(''); expect(fs.readFileSync(path.join(f.base, 'gh.log'), 'utf8')).not.toContain('gh release'); @@ -818,7 +820,7 @@ describe('release-cut: the 72-hour floor', () => { if (!schedEarly.ok) { expect(schedEarly.code).toBe('REFUSED_FLOOR'); expect(schedEarly.message).toContain('a scheduled run needs 69 h (72 h less 3 h cron grace)'); } const schedOk = plan(FLOOR_HOURS - SCHEDULED_GRACE_HOURS, true); expect(schedOk.ok, JSON.stringify(schedOk)).toBe(true); - if (schedOk.ok) expect(schedOk.plan.notes).toContain('## gstack v1.0.4 (regular release)'); + if (schedOk.ok) expect(schedOk.plan.notes).toContain('## gstack v1.0.4\n'); const handInGrace = plan(70); expect(handInGrace.ok).toBe(false); if (!handInGrace.ok) expect(handInGrace.code).toBe('REFUSED_FLOOR'); @@ -1052,9 +1054,10 @@ describe('release-cut: the security exception', () => { if (!next.ok) return; expect(next.plan.exception).toBeNull(); expect(next.plan.prevTag).toBe('v1.0.4'); - expect(next.plan.notes).toContain('## gstack v1.0.6 (regular release)'); - expect(next.plan.notes).toContain('2 versions since v1.0.4'); - expect(next.plan.notes).not.toContain('- **1.0.4**'); + expect(next.plan.notes).toContain('## gstack v1.0.6\n'); + expect(next.plan.ridingAlong).toBe(1); + expect(next.plan.notes).toContain('compare/v1.0.4...v1.0.6'); + expect(next.plan.notes).not.toContain('Hardens tar extraction.'); expect(next.plan.notes).not.toContain('Security release'); }, 30_000); @@ -1274,20 +1277,217 @@ describe.skipIf(process.platform === 'win32')('release-cut: refusals at the work }); describe('release-cut: notes', () => { - test('changelog headlines are the bold first line of each entry; versions order numerically', () => { - const entries = changelogEntries('# Changelog\n\n## [1.91.221.0] - 2026-10-25\n\n**The updater no longer skips.** More.\n\n### Fixed\n- x\n\n## [1.91.99.0] - 2026-10-01\n\n| a | b |\n\n**Older.**\n'); - expect(entries).toEqual([{ version: '1.91.221.0', date: '2026-10-25', headline: 'The updater no longer skips.' }, { version: '1.91.99.0', date: '2026-10-01', headline: 'Older.' }]); - expect(changelogEntries('## [1.0.0] - 2026-01-01\n\nPlain lead with **some** bold.\n')[0]!.headline).toBe('Plain lead with some bold.'); + // A fixture CHANGELOG in the shapes main has held: fragment-era bullets with bold leads, a plain bullet, + // and an older per-version entry with "### Fixed" and "### Tests" headings and a paragraph lead. + const CHANGELOG = [ + '# Changelog', '', + '## [2.1.0.0] - 2026-11-14', '', + '- **/review now reads Rust files (GST-101).** It used to skip them.', '', + '- **The installer no longer deletes your config.** It kept a copy.', '', + '- **/ship\'s outside voice now reads the whole diff.** Before, it read half.', '', + '- `gstack-redact` now says its 16 MiB limit. Reported by @someone (#90).', '', + '## [2.0.1.0] - 2026-11-10', '', + 'Faster startup for every skill.', '', + '### Fixed', '- **`bin/x`**: the updater stops skipping a version. More text.', '', + '### Tests', '- The free suite is green again.', '', + '## [2.0.0.0] - 2026-11-01', '', + '**Already released.**', '', + ].join('\n'); + const sources: NotesSources = { + versions: { + '2.1.0.0': { pr: null, files: ['CHANGELOG.md', 'VERSION'], fragments: [ + { pr: 11, files: ['review/SKILL.md', 'changelog.d/rust.md'], changes: changesIn(['- **/review now reads Rust files (GST-101).** It used to skip them.']) }, + { pr: 12, files: ['bin/gstack-install', 'changelog.d/config.md'], changes: changesIn(['- **The installer no longer deletes your config.** It kept a copy.']) }, + { pr: 13, files: ['test/ship-review.test.ts', 'changelog.d/voice.md'], changes: changesIn(['### Changed', '', '- **/ship\'s outside voice now reads the whole diff.** Before, it read half.']) }, + ] }, + '2.0.1.0': { pr: 9, files: ['lib/startup.ts', 'VERSION', 'CHANGELOG.md'], fragments: [] }, + }, + }; + + // Value: protects=release bodies list each change in plain words with its PR, grouped, never a "see CHANGELOG.md" stub; fails_when=a bullet-only + // entry yields no line (the v1.99.x stubs), a change links the release commit's PR instead of its own, groups ignore headings or files, internal + // codes leak, or the compare link goes missing; why_new=the old notes printed one headline per version and fell back to "see CHANGELOG.md". + test('a fixture changelog becomes grouped lines with their PR links and the compare link at the bottom', () => { + const notes = releaseNotes({ repo: 'o/r', version: '2.1.0.0', date: '2026-11-14', prevVersion: '2.0.0.0', prevTag: 'v2.0.0.0', entries: changelogEntries(CHANGELOG), hotfix: false, sources }); + expect(notes.ok).toBe(true); + if (!notes.ok) return; + expect(notes.versions).toBe(2); + expect(notes.body).toBe([ + '## gstack v2.1.0.0', '', + "### What's new", '', + '- /review now reads Rust files. ([#11](https://github.com/o/r/pull/11))', + '- `gstack-redact` now says its 16 MiB limit.', + '- Faster startup for every skill. ([#9](https://github.com/o/r/pull/9))', '', + '### Fixes', '', + '- The installer no longer deletes your config. ([#12](https://github.com/o/r/pull/12))', + '- `bin/x`: the updater stops skipping a version. ([#9](https://github.com/o/r/pull/9))', '', + '### Changes for maintainers', '', + "- /ship's second-model review now reads the whole diff. ([#13](https://github.com/o/r/pull/13))", + '- The free suite is green again. ([#9](https://github.com/o/r/pull/9))', '', + '[Compare v2.0.0.0...v2.1.0.0](https://github.com/o/r/compare/v2.0.0.0...v2.1.0.0) · [Full changelog](https://github.com/o/r/blob/v2.1.0.0/CHANGELOG.md)', '', + ].join('\n')); + expect(notes.body).not.toContain('see CHANGELOG'); + expect(notes.body).not.toContain('Already released.'); expect(compareVersions('1.91.221.0', '1.91.99.0')).toBeGreaterThan(0); expect(compareVersions('1.91.9.0', '1.91.10.0')).toBeLessThan(0); }); - test('a span of a thousand versions stays under the notes cap and says how many were cut', () => { - const entries = Array.from({ length: 1000 }, (_, i) => ({ version: '1.91.' + (i + 1) + '.0', date: '2026-10-20', headline: 'Headline number ' + i + ' with enough words to take some room in the body.' })); - const notes = releaseNotes({ repo: 'o/r', version: '1.91.1000.0', date: '2026-10-26', prevVersion: '1.91.0.0', prevTag: null, entries, hotfix: false }); - expect(notes.length).toBeLessThanOrEqual(NOTES_CAP); - expect(notes).toMatch(/- \.\.\.and \d+ more versions; see CHANGELOG\.md/); - expect(notes).toContain('1000 versions since v1.91.0.0'); - expect(notes.split('\n')[0]).toBe('## gstack v1.91.1000.0 (regular release)'); + // Value: protects=a security fix's release line keeps its CVE or GHSA advisory id while internal issue codes still drop; fails_when=the issue-code + // stripper removes an advisory id; why_new=the stripper matched any CODE-123 in parentheses; seam=none; no_claim=GitHub's advisory formats beyond these two. + test('a change line keeps CVE and GHSA ids and drops internal issue codes', () => { + expect(changeLine('**Browse no longer follows symlinks out of the profile dir (CVE-2026-41234).** More.')).toBe('Browse no longer follows symlinks out of the profile dir (CVE-2026-41234).'); + expect(changeLine('**The tar path is safe again (GHSA-4x5v-abcd-1234, reported by a user).** More.')).toBe('The tar path is safe again (GHSA-4x5v-abcd-1234, reported by a user).'); + expect(changeLine('**/review now reads Rust files (GST-101).** More.')).toBe('/review now reads Rust files.'); + }); + + // Value: protects=a cut fails loudly instead of publishing a stub; fails_when=a version with an empty entry or a span with no entry still + // yields notes; why_new=the old notes always rendered, padding gaps with "see CHANGELOG.md". + test('a version with no change or a missing entry refuses instead of publishing a stub', () => { + const base = { repo: 'o/r', date: '2026-11-14', prevVersion: '2.0.0.0', prevTag: 'v2.0.0.0', hotfix: false }; + const hollow = releaseNotes({ ...base, version: '2.1.0.0', entries: changelogEntries('## [2.1.0.0] - 2026-11-14\n\n## [2.0.5.0] - 2026-11-12\n\n- One change.\n') }); + expect(hollow).toEqual({ ok: false, why: 'no change to list in the CHANGELOG entry of v2.1.0.0; write the entry before cutting the release' }); + const missing = releaseNotes({ ...base, version: '2.1.0.0', entries: changelogEntries('## [2.0.0.0] - 2026-11-01\n\n- Old.\n') }); + expect(missing).toEqual({ ok: false, why: 'CHANGELOG.md at the release has no entry for v2.1.0.0 or any version since v2.0.0.0' }); + }); + + // Value: protects=a release names the version it ships, never an older one's changes under its heading; fails_when=a span holding only an older + // entry than the release version still publishes; why_new=the span filter took any entry in (prev, version]; seam=none; no_claim=folded versions. + test('a release version with no entry of its own refuses even when an older version in the span has one', () => { + const notes = releaseNotes({ repo: 'o/r', version: '2.1.0.0', date: '2026-11-14', prevVersion: '2.0.0.0', prevTag: 'v2.0.0.0', hotfix: false, entries: changelogEntries('## [2.0.5.0] - 2026-11-12\n\n- One change.\n\n## [2.0.0.0] - 2026-11-01\n\n- Old.\n') }); + expect(notes).toEqual({ ok: false, why: 'CHANGELOG.md at the release has no entry for v2.1.0.0, only for the older v2.0.5.0; write the entry before cutting the release' }); + }); + + // Value: protects=a fragment links the PR of the commit that added it even when its own text cites another PR; fails_when=the lookup reads the + // commit's patch along with its subject and takes the last "(#N)" it finds; why_new=git log with --diff-merges printed the patch; seam=a real git repo. + test('a fragment whose body cites another PR still links the PR of the commit that added it', () => { + const f = fixture(); + fs.mkdirSync(path.join(f.seed, 'changelog.d'), { recursive: true }); + fs.writeFileSync(path.join(f.seed, 'changelog.d', 'redact.md'), '- **gstack-redact now says its size limit.** It follows the limit #7 added (#7).\n'); + git(f.seed, 'add', '-A'); + git(f.seed, 'commit', '-q', '-m', 'Say the redact size limit (#42)'); + fs.writeFileSync(path.join(f.seed, 'CHANGELOG.md'), fs.readFileSync(path.join(f.seed, 'CHANGELOG.md'), 'utf8').replace('# Changelog\n', '# Changelog\n\n## [1.0.4] - 2026-10-24\n\n- **gstack-redact now says its size limit.** It follows the limit #7 added (#7).\n')); + fs.rmSync(path.join(f.seed, 'changelog.d', 'redact.md')); + git(f.seed, 'add', '-A'); + git(f.seed, 'commit', '-q', '-m', 'v1.0.4 release (#43)'); + git(f.seed, 'push', '-q', 'origin', 'main'); + f.refresh(); + const sources = changeSources(f.git, f.shas['1.0.3']!, 'origin/main'); + expect(sources.versions['1.0.4']?.pr).toBeNull(); + expect(sources.versions['1.0.4']?.fragments.map(s => s.pr)).toEqual([42]); + }); + + // Value: protects=planRelease reads each change's PR from git and refuses a cut whose CHANGELOG lacks the version; fails_when=the fragment's + // own PR is not found along main, the release commit's PR is linked instead, or a missing entry still cuts; why_new=the notes never read git. + test('a cut links the PR that added each fragment, not the release commit, and refuses a version with no entry', () => { + const f = fixture(); + const first = planRelease({ repo: f.repo, git: f.git, gh: f.gh }); + expect(first.ok).toBe(true); + if (!first.ok) return; + expect(cutRelease(first.plan, { repo: f.repo, git: f.git, gh: f.gh, notesDir: f.base }).ok).toBe(true); + const fragment = '- **The lease no longer blocks a push.** It waits instead.\n'; + fs.mkdirSync(path.join(f.seed, 'changelog.d'), { recursive: true }); + fs.writeFileSync(path.join(f.seed, 'changelog.d', 'lease.md'), fragment); + fs.writeFileSync(path.join(f.seed, 'lease.ts'), 'export const lease = 1;\n'); + git(f.seed, 'add', '-A'); + git(f.seed, 'commit', '-q', '-m', 'Stop the lease blocking a push (#42)'); + const changelog = fs.readFileSync(path.join(f.seed, 'CHANGELOG.md'), 'utf8').replace('# Changelog\n', '# Changelog\n\n## [1.0.4] - 2026-10-24\n\n' + fragment); + fs.writeFileSync(path.join(f.seed, 'CHANGELOG.md'), changelog); + fs.writeFileSync(path.join(f.seed, 'VERSION'), '1.0.4\n'); + fs.rmSync(path.join(f.seed, 'changelog.d', 'lease.md')); + git(f.seed, 'add', '-A'); + git(f.seed, 'commit', '-q', '-m', 'v1.0.4 release (#43)'); + git(f.seed, 'push', '-q', 'origin', 'main'); + const stamp = git(f.seed, 'rev-parse', 'HEAD'); + f.refresh(); + const r = planRelease({ repo: f.repo, ref: stamp, git: f.git, gh: f.gh, now: pastFloor }); + expect(r.ok, JSON.stringify(r)).toBe(true); + if (!r.ok) return; + expect(r.plan.notes).toContain('### Fixes\n\n- The lease no longer blocks a push. ([#42](https://github.com/o/r/pull/42))'); + expect(r.plan.notes).not.toContain('#43'); + + fs.writeFileSync(path.join(f.seed, 'VERSION'), '1.0.5\n'); + fs.writeFileSync(path.join(f.seed, 'CHANGELOG.md'), changelog.replace('# Changelog\n', '# Changelog\n\n## [1.0.5] - 2026-10-25\n\n')); + git(f.seed, 'commit', '-q', '-am', 'v1.0.5 with an empty entry'); + git(f.seed, 'push', '-q', 'origin', 'main'); + const bare = git(f.seed, 'rev-parse', 'HEAD'); + f.refresh(); + const refused = planRelease({ repo: f.repo, ref: bare, git: f.git, gh: f.gh, now: pastFloor }); + expect(refused.ok).toBe(false); + if (!refused.ok) expect([refused.code, refused.message]).toEqual(['NOTES_MISSING', 'no change to list in the CHANGELOG entry of v1.0.5; write the entry before cutting the release']); + }); + // Value: protects=each change links the PR whose squash commit added its own fragment file; fails_when=a change links another fragment's PR because + // its words appear inside that fragment, or a fragment file name reused after a release links the later PR; why_new=the lookup matched CHANGELOG + // prose against fragment bodies and took a file name's newest add; seam=a real git repo; no_claim=merge-commit histories. + test('each change links the PR that added its own fragment file, even with overlapping words or a reused fragment name', () => { + const f = fixture(); + const first = planRelease({ repo: f.repo, git: f.git, gh: f.gh }); + expect(first.ok).toBe(true); + if (!first.ok) return; + expect(cutRelease(first.plan, { repo: f.repo, git: f.git, gh: f.gh, notesDir: f.base }).ok).toBe(true); + fs.mkdirSync(path.join(f.seed, 'changelog.d'), { recursive: true }); + const commit = (subject: string, files: Record) => { + for (const [file, text] of Object.entries(files)) { + if (text === null) fs.rmSync(path.join(f.seed, file)); + else fs.writeFileSync(path.join(f.seed, file), text); + } + git(f.seed, 'add', '-A'); + git(f.seed, 'commit', '-q', '-m', subject); + }; + const lease = '- **The lease no longer blocks a push.**\n'; + const retry = '- **The lease retries once.** It builds on the fix where the lease no longer blocks a push.\n'; + const tar = '- **The tar path is safe again.**\n'; + commit('Stop the lease blocking a push (#42)', { 'changelog.d/fix.md': lease }); + commit('Retry the lease once (#44)', { 'changelog.d/a-retry.md': retry }); + let changelog = fs.readFileSync(path.join(f.seed, 'CHANGELOG.md'), 'utf8').replace('# Changelog\n', '# Changelog\n\n## [1.0.4] - 2026-10-24\n\n' + retry + '\n' + lease); + commit('v1.0.4 release (#43)', { 'CHANGELOG.md': changelog, VERSION: '1.0.4\n', 'changelog.d/fix.md': null, 'changelog.d/a-retry.md': null }); + commit('Make the tar path safe (#50)', { 'changelog.d/fix.md': tar }); + changelog = changelog.replace('# Changelog\n', '# Changelog\n\n## [1.0.5] - 2026-10-25\n\n' + tar); + commit('v1.0.5 release (#51)', { 'CHANGELOG.md': changelog, VERSION: '1.0.5\n', 'changelog.d/fix.md': null }); + git(f.seed, 'push', '-q', 'origin', 'main'); + const stamp = git(f.seed, 'rev-parse', 'HEAD'); + f.refresh(); + const r = planRelease({ repo: f.repo, ref: stamp, git: f.git, gh: f.gh, now: pastFloor }); + expect(r.ok, JSON.stringify(r)).toBe(true); + if (!r.ok) return; + const link = (n: number) => '([#' + n + '](https://github.com/o/r/pull/' + n + '))'; + expect(r.plan.notes).toContain('- The lease no longer blocks a push. ' + link(42)); + expect(r.plan.notes).toContain('- The lease retries once. ' + link(44)); + expect(r.plan.notes).toContain('- The tar path is safe again. ' + link(50)); + expect(r.plan.notes.match(/\/pull\//g)?.length).toBe(3); + }); + + // Value: protects=a long span still publishes, cut to the cap with a pointer to the full changelog; fails_when=notes over the cap refuse the + // cut, run past the cap, or drop changes without saying how many; why_new=the cap refused the whole release; seam=none; no_claim=GitHub's own limit. + test('notes over the cap keep the newest changes and send the rest to the full changelog', () => { + const entries = Array.from({ length: 1000 }, (_, i) => ({ version: '2.0.' + (i + 1) + '.0', date: '2026-11-10', changes: [{ text: 'Change number ' + i + ' with enough words to take some room in the body.', heading: '' }] })); + const long = releaseNotes({ repo: 'o/r', date: '2026-11-14', prevVersion: '2.0.0.0', prevTag: 'v2.0.0.0', hotfix: false, version: '2.0.1000.0', entries }); + expect(long.ok).toBe(true); + if (!long.ok) return; + expect(long.versions).toBe(1000); + expect(long.body.length).toBeLessThanOrEqual(NOTES_CAP); + expect(long.body).toContain('- Change number 999 with enough words'); + expect(long.body).not.toContain('- Change number 0 with'); + const more = /\n(\d+) more changes are in the \[full changelog\]\(https:\/\/github\.com\/o\/r\/blob\/v2\.0\.1000\.0\/CHANGELOG\.md\)\.\n/.exec(long.body); + expect(more).not.toBeNull(); + expect(long.body.match(/^- Change number/gm)!.length + Number(more![1])).toBe(1000); + expect(long.body.trimEnd().endsWith('[Full changelog](https://github.com/o/r/blob/v2.0.1000.0/CHANGELOG.md)')).toBe(true); + }); + + // Value: protects=a "## " heading a fragment carries into the CHANGELOG keeps every change after it in that version; fails_when=the version's + // section ends at that heading and later changes vanish from the notes; why_new=any "## " line ended a version; seam=none; no_claim=lib/restamp.ts. + test('a "## " heading inside a version keeps the changes after it', () => { + const entries = changelogEntries('# Changelog\n\n## [2.1.0.0] - 2026-11-14\n\n- **One.**\n\n## Notes for contributors\n\n- **Two.**\n\n## [2.0.0.0] - 2026-11-01\n\n- Old.\n'); + expect(entries.map(e => [e.version, e.changes.map(c => [c.text, c.heading])])).toEqual([ + ['2.1.0.0', [['**One.**', ''], ['**Two.**', 'Notes for contributors']]], + ['2.0.0.0', [['Old.', '']]], + ]); + }); + + // Value: protects=a parenthetical that only starts like an issue code (SHA-256 ..., UTF-8 ...) stays in the line while a list of issue codes still + // drops; fails_when=the stripper removes "(SHA-256 of its bytes, ...)"; why_new=the stripper dropped any parenthetical opening with CODE-123; + // seam=none; no_claim=a bare "(SHA-256)", which has an issue code's shape. + test('a change line keeps a parenthetical that only starts like an issue code', () => { + expect(changeLine('**Receipts now pin each file (SHA-256 of its bytes, not its name).** More.')).toBe('Receipts now pin each file (SHA-256 of its bytes, not its name).'); + expect(changeLine('**Reports lead with failures (GST-1455, GST-2349).** More.')).toBe('Reports lead with failures.'); }); }); diff --git a/docs/releases.md b/docs/releases.md index 322c4d318..ca1ce0dfe 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -30,9 +30,10 @@ change or a week-old stable can trigger one. A cut takes the newest green commit on main and: 1. tags it `v` (the VERSION file at that commit, an annotated tag); -2. publishes a GitHub Release whose notes are one line per CHANGELOG version - since the previous release, with a compare link and a link to the full - CHANGELOG at that tag; +2. publishes a GitHub Release whose notes list every change in the CHANGELOG + versions since the previous release, one plain line each with the pull + request that made it, then a compare link and a link to the full CHANGELOG + at that tag ([Release notes](#release-notes)); 3. fast-forwards the `stable` branch to it. A tag and its release never change. `stable` is a moving pointer: always a @@ -101,6 +102,45 @@ finished by the next run, by cron or by hand: `stable` itself stays a candidate until its release exists, and its notes compare against the release tag before it. +## Release notes + +A release's notes list every change in the CHANGELOG versions it ships. A +change is a top-level bullet of a version's entry, or a paragraph that is not a +bullet. Its line is the bullet's bold lead when that lead is a whole sentence, +else its first sentence, so a fragment's first sentence is what people read on +the release page: say what changed for them, in plain words. A parenthesis +that holds only issue codes, such as `(GST-101)` or `(GST-1455, GST-2349)`, +is dropped; one that says more, such as `(SHA-256 of the file)`, and CVE and +GHSA ids stay. "Outside voice" reads "second-model review". A `## ` heading +inside a fragment is read like a `### ` one and never ends its version. + +Each line links the pull request that made the change, read from git and never +from the change's words. The commit that added a version's `## [version]` +heading folded the `changelog.d/` fragments it deleted, in path order, so the +version lists each of those fragments' changes, as the fragment read just +before the fold, linked to the trailing `(#N)` of the squash commit that added +that file (wherever that commit sits, since a release can fold fragments that +landed before the previous one; a later pull request that reuses the file name +never takes the link). Changes the version holds past its fragments', and every +change of an older version written straight into the CHANGELOG, link the +commit that added the version's heading; a release commit links nothing. +Lines sit under three headings, read in this order: + +1. the heading the change sits under, inside its fragment when it has one: + `### Added` is What's new, `### Fixed` is Fixes, and `### Tests` or + `### For contributors` is Changes for maintainers; +2. Changes for maintainers when its pull request touched only tests, CI and + gstack's own release tooling (`test/`, `crew/`, `.github/`), or its line + names that machinery (receipts, the release gate, the merge queue); +3. Fixes when the line says "no longer", "again" or "fix"; What's new otherwise. + +A cut whose CHANGELOG has no entry for its version, or holds a version entry +that lists no change, stops with `NOTES_MISSING` instead of publishing empty +notes. Notes over 60,000 characters keep the changes that fit, dropping +maintainer changes first, and say how many more are in the full changelog. An upgrade step or a summary +sentence can be added by hand after the cut with +`gh release edit v --notes-file `; that edits the release page only. + ## The daily check @@ -441,7 +481,7 @@ first, then promote. Run the workflow with `dry_run=true` (the default for a manual run) to see the plan without changing anything: the candidate, its VERSION and tag, the stable -move, how many version lines the notes would carry, every skipped commit with +move, how many change lines the notes would carry, every skipped commit with its reason, the floor verdict, and the exact commands a real cut would run. The scheduled runs are never dry runs. @@ -454,8 +494,8 @@ gh run watch The step summary carries the same plan plus the full release notes. A pull request that touches `.github/workflows/weekly-release.yml`, -`crew/scripts/release-cut.ts`, `crew/scripts/release-cadence.ts` or -`lib/changelog-fragments.ts` runs the same dry run against main as its own job +`crew/scripts/release-cut.ts`, `crew/scripts/release-notes.ts`, +`crew/scripts/release-cadence.ts` or `lib/changelog-fragments.ts` runs the same dry run against main as its own job (`Dry run against main`, read-only token), once plain and once as the daily check, so a change to the release tooling is exercised against real check runs before it merges. @@ -542,4 +582,5 @@ reset --hard 'v'`. Its next update check fast-forwards it to | `DAILY: no-op: ...`, `DAILY: wait: ...` | the daily check found no trigger, or an important change still under its 24-hour floor (`NEXT_ALLOWED:` follows); exit 0 with a notice | | `IMPORTANT_UNGATED: ...` | an important change landed but no green, gated commit holds it yet; informational | | `NO_RELEASE_PR: ...` | the candidate's VERSION is already released on an earlier commit (no release PR landed since that cut): the Captain stamps a release PR. A plain cut always reports it; the daily check reports it only when a trigger is due. Exit 1 (0, with a warning, on a dry run) | +| `NOTES_MISSING: ...` | the CHANGELOG at the candidate has no entry for its version, or a version in the span lists no change ([Release notes](#release-notes)); nothing is tagged or published. Exit 1 | | `STABLE_STALE: ...` | stable is 7 days old and main moved, but nothing newer is green and gated; exit 1 (0 on a dry run) | diff --git a/scripts/harness-pins/scripts/test-pr-profile.ts.json b/scripts/harness-pins/scripts/test-pr-profile.ts.json index c22d2e373..1c96603f1 100644 --- a/scripts/harness-pins/scripts/test-pr-profile.ts.json +++ b/scripts/harness-pins/scripts/test-pr-profile.ts.json @@ -1 +1 @@ -{"blob":"285f2a8b910fdf6503c555810a96995c7615f9df","since":6,"nonBehavioral":"test-pr-profile.ts only repoints paths and an import to files that moved unchanged into crew/ (GST-1833), on top of main's plain-title entries that no PR-gate case reads; no verdict can change"} +{"blob":"6f9f93ff672653c72d9e0d97ff9499b6062890a3","since":6,"nonBehavioral":"adds crew/scripts/release-notes.ts to the free-only list beside release-cut.ts"} diff --git a/scripts/test-pr-profile.ts b/scripts/test-pr-profile.ts index 285f2a8b9..6f9f93ff6 100644 --- a/scripts/test-pr-profile.ts +++ b/scripts/test-pr-profile.ts @@ -292,6 +292,7 @@ export const FREE_ONLY_PR_FILES = [ '.github/workflows/release-gate.yml', // The 8-hour release gate on main: it dispatches evals.yml on main's head; no PR-gate case reads it, and it never gates a PR. '.github/workflows/weekly-release.yml', // The Monday release cut (tag, stable, GitHub Release): reads check runs on main; no paid case reads it, and it never gates a PR. 'crew/scripts/release-cut.ts', // The release cut's logic, run only by weekly-release.yml; covered by the free crew/test/release-cut.test.ts. + 'crew/scripts/release-notes.ts', // The release cut's notes, run only by weekly-release.yml; covered by the free crew/test/release-cut.test.ts. '.github/actionlint.yaml', // Runner labels for actionlint only. 'scripts/ship-measure-sweep.ts', // The weekly sweep CLI; it launches paid cases, never runs inside one. '.github/workflows/version-gate.yml', diff --git a/test/weekly-release-workflow.test.ts b/test/weekly-release-workflow.test.ts index 0ad32aaef..bbd68f31d 100644 --- a/test/weekly-release-workflow.test.ts +++ b/test/weekly-release-workflow.test.ts @@ -40,7 +40,7 @@ describe('weekly-release.yml', () => { expect(wf.on.workflow_dispatch.inputs.regression).toMatchObject({ type: 'string', default: '' }); expect(wf.on.workflow_dispatch.inputs.dry_run).toMatchObject({ type: 'boolean', default: true }); expect(wf.on.workflow_dispatch.inputs.ref).toMatchObject({ type: 'string', default: '' }); - expect(wf.on.pull_request).toEqual({ paths: ['.github/workflows/weekly-release.yml', 'crew/scripts/release-cut.ts', 'crew/scripts/release-cadence.ts', 'lib/changelog-fragments.ts'] }); + expect(wf.on.pull_request).toEqual({ paths: ['.github/workflows/weekly-release.yml', 'crew/scripts/release-cut.ts', 'crew/scripts/release-notes.ts', 'crew/scripts/release-cadence.ts', 'lib/changelog-fragments.ts'] }); expect(wf.concurrency).toEqual({ group: "weekly-release-${{ github.event.pull_request.number || 'cut' }}", 'cancel-in-progress': false }); expect(wf.permissions).toEqual({}); expect(Object.keys(wf.jobs)).toEqual(['cut', 'dry-run']);