mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-18 22:24:17 +01:00
Release notes list every change with its pull request instead of "see CHANGELOG.md" (#4390)
GitHub release pages now list every change a release ships, one plain line each, linked to the pull request that made it, instead of one headline per version or "see CHANGELOG.md". Why: the release page is where people read what changed, and recent releases went out saying only "see CHANGELOG.md". Nothing to do: the next release uses it; a release with no CHANGELOG entry stops with `NOTES_MISSING` instead of publishing a stub. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
1 parent
b1c32824fd
commit
a9da30363c
12 files changed
+551
-118
No files matched your search
@@ -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<VERSION>`, 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 <sha on main>`, held by the same floor. Details, the floor's
|
||||
refusal codes and the "nothing green in the window" failure mode:
|
||||
|
||||
+12
-78
@@ -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<VERSION>, 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<T>(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 <nonce>`. 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;
|
||||
|
||||
@@ -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<version> 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<string, VersionSource> }
|
||||
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<string, { pr: number | null; stamp: boolean; files: string[]; folded: string[] }>();
|
||||
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<Group, string[]> = { 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 };
|
||||
}
|
||||
@@ -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<string, string | undefined> = { ...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::');
|
||||
});
|
||||
});
|
||||
+226
-26
@@ -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('<details><summary>Release notes</summary>');
|
||||
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<string, string | null>) => {
|
||||
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.');
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user