Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Group stable release notes by bump level (#2696)

Andrew Mikofalvy0742553d12ee
diff --git a/.github/workflows/promote-stable.yml b/.github/workflows/promote-stable.yml
index 471dae708..481d75cf0 100644
--- a/.github/workflows/promote-stable.yml
+++ b/.github/workflows/promote-stable.yml
@@ -277,7 +277,6 @@ jobs:
GH_TOKEN: ${{ steps.app-token.outputs.token }}
STABLE_TAG: ${{ steps.ver.outputs.stable_tag }}
BETA_SHA: ${{ steps.ver.outputs.beta_sha }}
- STABLE_VERSION: ${{ steps.ver.outputs.stable_version }}
# Pass the resolved beta tag via env to keep ${{ }} expression
# interpolation out of the run: block — direct ${{ }} substitution
# in shell is a script-injection foothold (a malicious tag value
@@ -311,40 +310,47 @@ jobs:
BETA_TAGS_IN_RANGE=$(git tag --list 'v*-beta.*' --merged "$BETA_SHA" --sort=version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+-beta\.[0-9]+$' || true)
fi
- # Under the zero-commit-bump cadence, beta release bodies are
- # the source of truth — packages/*/CHANGELOG.md no longer
- # accumulates per-beta entries (only per-stable, written by
- # main-reset's `bun changeset version` at promotion time). Each
- # beta body now carries ONLY the delta introduced in that beta
- # (compute-next-beta.mjs filters against the prior beta's
- # embedded consumed-set marker), so simple concatenation across
- # the cycle's betas yields a clean cumulative changelog with no
- # duplication.
+ # Under the zero-commit-bump cadence, beta release bodies are the
+ # source of truth — packages/*/CHANGELOG.md no longer accumulates
+ # per-beta entries (only per-stable, written by main-reset's
+ # `bun changeset version` at promotion time). Each beta body carries
+ # ONLY the delta introduced in that beta (compute-next-beta.mjs filters
+ # against the prior beta's embedded consumed-set marker), so the cycle's
+ # betas concatenated are a clean, duplication-free set of the changes
+ # this stable ships.
#
- # Stripped from each body before concatenation:
- # - `<!-- ok-consumed-set: ... -->` markers (internal bookkeeping)
- # - `Delta since previous beta (...) — N new changesets.` header
- # (the per-beta subheading we emit here is the right framing)
- {
- printf '## %s\n\n' "$STABLE_VERSION"
- printf 'Stable promotion of beta %s.\n\n' "$BETA_TAG_INPUT"
- if [[ -n "$BETA_TAGS_IN_RANGE" ]]; then
- printf 'Aggregated changes since previous stable:\n\n'
- for tag in $BETA_TAGS_IN_RANGE; do
- BETA_VER=${tag#v}
- printf '### %s\n\n' "$BETA_VER"
- if BODY=$(gh release view "$tag" --json body --jq .body 2>/dev/null) && [[ -n "$BODY" ]]; then
- printf '%s\n' "$BODY" \
- | sed -E -e '/^<!-- ok-consumed-set:.*-->$/d' \
- -e '/^(Delta since previous beta|First beta of the cycle).*$/d' \
- | awk 'NF{p=1} p'
- else
- printf '_(release body unavailable for %s)_\n' "$tag"
- fi
- printf '\n'
- done
+ # aggregate-stable-changelog.mjs regroups that concatenation into one
+ # section per bump level (Major/Minor/Patch, empty levels omitted) and
+ # emits no preamble of its own: the GitHub Release title already carries
+ # the version, and under delta versioning the promoted beta's name no
+ # longer equals the stable version, so the old "## X.Y.Z / Stable
+ # promotion of beta … / Aggregated changes since previous stable" header
+ # was both redundant and inaccurate. The script also drops the internal
+ # `<!-- ok-consumed-set: … -->` markers and the per-beta "Delta since
+ # previous beta" / "First beta of the cycle" lead lines.
+ RAW_BODIES=$(mktemp)
+ UNAVAILABLE=""
+ for tag in $BETA_TAGS_IN_RANGE; do
+ if BODY=$(gh release view "$tag" --json body --jq .body 2>/dev/null) && [[ -n "$BODY" ]]; then
+ printf '%s\n\n' "$BODY" >> "$RAW_BODIES"
+ else
+ UNAVAILABLE="${UNAVAILABLE:+$UNAVAILABLE, }${tag}"
fi
- } > "$BODY_FILE"
+ done
+
+ node scripts/aggregate-stable-changelog.mjs < "$RAW_BODIES" > "$BODY_FILE"
+
+ # A stable with no resolvable beta changelog (no betas in range, or
+ # every body empty/unavailable) still needs a non-empty release body.
+ if [[ ! -s "$BODY_FILE" ]]; then
+ printf 'No changelog entries.\n' > "$BODY_FILE"
+ fi
+
+ # Surface any beta whose body could not be fetched so its changes are
+ # not silently missing from the aggregated notes.
+ if [[ -n "$UNAVAILABLE" ]]; then
+ printf '\n_Release body unavailable for: %s — see the per-beta releases for those changes._\n' "$UNAVAILABLE" >> "$BODY_FILE"
+ fi
# GitHub rejects release bodies over 125,000 chars with HTTP 422.
# A long beta cycle (dozens of betas, each contributing its delta)
diff --git a/knip.config.ts b/knip.config.ts
index 6686f6d7c..1dd482fb9 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -46,6 +46,8 @@ export default {
'scripts/compute-next-beta.test.mjs': ['files'],
'scripts/compute-stable-version.mjs': ['files'],
'scripts/compute-stable-version.test.mjs': ['files'],
+ 'scripts/aggregate-stable-changelog.mjs': ['files'],
+ 'scripts/aggregate-stable-changelog.test.mjs': ['files'],
'scripts/check-license-fields.test.mjs': ['files'],
'scripts/check-gate-catches-build-errors.test.mjs': ['files'],
'scripts/bun-install-ci.test.mjs': ['files'],
diff --git a/scripts/aggregate-stable-changelog.mjs b/scripts/aggregate-stable-changelog.mjs
new file mode 100644
index 000000000..0ca0d12d6
--- /dev/null
+++ b/scripts/aggregate-stable-changelog.mjs
@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * Build a stable release's changelog by accumulating the per-beta Changesets
+ * bodies of the cycle into ONE section per bump level.
+ *
+ * The stable GitHub Release title already carries the version (e.g. `v0.32.0`),
+ * and under the delta-versioning cadence the promoted beta's name no longer
+ * matches the stable version, so the old preamble ("## 0.32.0", "Stable
+ * promotion of beta v…", "Aggregated changes since previous stable:") was both
+ * redundant and inaccurate. This drops all of it. It also drops the per-beta
+ * `### vX.Y.Z-beta.N` grouping the promote workflow used to emit: instead every
+ * bullet from every beta in the cycle is merged under a single
+ * `### Major Changes` / `### Minor Changes` / `### Patch Changes` heading, in
+ * that order, with any empty level omitted entirely.
+ *
+ * Input is the raw beta release bodies of the cycle concatenated on stdin (the
+ * promote workflow fetches them with `gh release view`). Each raw beta body is
+ * the Changesets delta for that beta — an optional lead line, then
+ * `### <Level> Changes` subsections with `- ` bullets, then an internal
+ * `<!-- ok-consumed-set: … -->` marker. Concatenating them yields repeated
+ * `### <Level> Changes` headings; this regroups every bullet by level. Beta
+ * boundaries are irrelevant to the grouping, so no separator is needed — the
+ * only per-beta lines that must not leak into the changelog (the consumed-set
+ * marker and the "Delta since previous beta" / "First beta of the cycle" lead)
+ * are dropped by line pattern.
+ *
+ * Bullets keep the order they arrive in (betas are fed oldest-first, so within a
+ * level the changes read in the order they were introduced), and each bullet's
+ * body — including indented continuation paragraphs — is preserved verbatim.
+ *
+ * Usage: node scripts/aggregate-stable-changelog.mjs < concatenated-beta-bodies
+ * Emits the merged changelog markdown to stdout (empty string if there are no
+ * level sections at all). Pure text transform; no git, no network.
+ */
+import { pathToFileURL } from 'node:url';
+
+// Order the sections render in. Also the bucket set.
+const LEVELS = ['Major', 'Minor', 'Patch'];
+
+// A Changesets bump-level heading. Beta bodies emit these at h3 (`### Minor
+// Changes`); tolerate h2–h4 so a heading-level tweak upstream can't silently
+// drop a whole section.
+const LEVEL_HEADING = /^#{2,4} (Major|Minor|Patch) Changes\s*$/;
+
+// Per-beta bookkeeping lines that are not user-facing changelog content:
+// - the consumed-set marker compute-next-beta.mjs embeds for delta filtering
+// - the "Delta since previous beta (…)" / "First beta of the cycle" lead line
+const STRIP_LINE =
+ /^(?:<!-- ok-consumed-set:.*-->|Delta since previous beta\b.*|First beta of the cycle\b.*)\s*$/;
+
+/**
+ * @param {string} input Concatenated raw beta release bodies.
+ * @returns {string} Merged changelog: `### <Level> Changes` sections (Major →
+ * Minor → Patch), empty levels omitted. Trailing newline when non-empty;
+ * empty string when no level sections were found.
+ */
+export function aggregateStableChangelog(input) {
+ const buckets = { Major: [], Minor: [], Patch: [] };
+ let level = null;
+ let block = null;
+
+ const flush = () => {
+ if (level && block) {
+ // Drop trailing blank lines so bullets join with exactly one blank line.
+ while (block.length && block[block.length - 1].trim() === '') block.pop();
+ if (block.length) buckets[level].push(block.join('\n'));
+ }
+ block = null;
+ };
+
+ for (const line of input.split('\n')) {
+ if (STRIP_LINE.test(line)) continue;
+ const heading = LEVEL_HEADING.exec(line);
+ if (heading) {
+ flush();
+ level = heading[1];
+ continue;
+ }
+ if (line.startsWith('- ')) {
+ // A new top-level bullet starts a new block; its indented continuation
+ // lines and interleaved blank lines accrue until the next bullet/heading.
+ flush();
+ block = [line];
+ continue;
+ }
+ if (block) block.push(line);
+ // Lines before the first bullet of a section (blank lines, stray prose)
+ // are dropped — only bullet blocks under a level heading survive.
+ }
+ flush();
+
+ const out = [];
+ for (const lvl of LEVELS) {
+ if (buckets[lvl].length === 0) continue;
+ out.push(`### ${lvl} Changes`, '', buckets[lvl].join('\n\n'), '');
+ }
+ const body = out.join('\n').replace(/\n+$/, '');
+ return body ? `${body}\n` : '';
+}
+
+function main() {
+ const chunks = [];
+ process.stdin.on('data', (c) => chunks.push(c));
+ process.stdin.on('end', () => {
+ process.stdout.write(aggregateStableChangelog(Buffer.concat(chunks).toString('utf8')));
+ });
+}
+
+// Run main() only as a CLI, not when imported by the test file.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+ main();
+}
diff --git a/scripts/aggregate-stable-changelog.test.mjs b/scripts/aggregate-stable-changelog.test.mjs
new file mode 100644
index 000000000..0b90da533
--- /dev/null
+++ b/scripts/aggregate-stable-changelog.test.mjs
@@ -0,0 +1,114 @@
+import { describe, expect, test } from 'bun:test';
+import { aggregateStableChangelog } from './aggregate-stable-changelog.mjs';
+
+// A raw beta body as produced by the beta cadence: a lead line, one bump-level
+// subsection, then the internal consumed-set marker.
+function betaBody({ lead, section }) {
+ return `${lead}\n\n${section}\n\n<!-- ok-consumed-set: ["x"] -->\n`;
+}
+
+describe('aggregateStableChangelog', () => {
+ test('merges bullets from many betas into one section per level (Major → Minor → Patch)', () => {
+ const input = [
+ betaBody({
+ lead: 'Delta since previous beta (v0.31.0-beta.0) — 1 new changeset.',
+ section: '### Minor Changes\n\n- Minor from beta.1',
+ }),
+ betaBody({
+ lead: 'Delta since previous beta (v0.31.0-beta.1) — 1 new changeset.',
+ section: '### Patch Changes\n\n- Patch from beta.2',
+ }),
+ betaBody({
+ lead: 'Delta since previous beta (v0.31.0-beta.2) — 1 new changeset.',
+ section: '### Patch Changes\n\n- Patch from beta.3',
+ }),
+ betaBody({
+ lead: 'First beta of the cycle.',
+ section: '### Major Changes\n\n- Major from beta.4',
+ }),
+ ].join('\n');
+
+ expect(aggregateStableChangelog(input)).toBe(
+ [
+ '### Major Changes',
+ '',
+ '- Major from beta.4',
+ '',
+ '### Minor Changes',
+ '',
+ '- Minor from beta.1',
+ '',
+ '### Patch Changes',
+ '',
+ '- Patch from beta.2',
+ '',
+ '- Patch from beta.3',
+ '',
+ ].join('\n'),
+ );
+ });
+
+ test('omits a level entirely when it has no changesets', () => {
+ const input = betaBody({
+ lead: 'First beta of the cycle.',
+ section: '### Patch Changes\n\n- Only a patch',
+ });
+ const out = aggregateStableChangelog(input);
+ expect(out).toBe('### Patch Changes\n\n- Only a patch\n');
+ expect(out).not.toContain('Major Changes');
+ expect(out).not.toContain('Minor Changes');
+ });
+
+ test('drops no preamble of its own — no version header or promotion note', () => {
+ const out = aggregateStableChangelog(
+ betaBody({ lead: 'First beta of the cycle.', section: '### Minor Changes\n\n- A change' }),
+ );
+ expect(out.startsWith('### Minor Changes')).toBe(true);
+ expect(out).not.toContain('Stable promotion of beta');
+ expect(out).not.toContain('Aggregated changes since previous stable');
+ expect(out).not.toMatch(/^## \d/m);
+ });
+
+ test('strips per-beta bookkeeping lines (consumed-set marker, delta/first-beta lead)', () => {
+ const out = aggregateStableChangelog(
+ betaBody({
+ lead: 'Delta since previous beta (v1.0.0-beta.0) — 2 new changesets.',
+ section: '### Patch Changes\n\n- A patch',
+ }),
+ );
+ expect(out).not.toContain('ok-consumed-set');
+ expect(out).not.toContain('Delta since previous beta');
+ expect(out).not.toContain('First beta of the cycle');
+ });
+
+ test('preserves a bullet body verbatim, including indented continuation paragraphs', () => {
+ const bullet = [
+ '- Report a bug from inside the app. Opens from Help → Report a Bug…',
+ '',
+ ' A second paragraph, indented two spaces, with `code` and a — dash.',
+ '',
+ ' A third paragraph.',
+ ].join('\n');
+ const out = aggregateStableChangelog(`### Minor Changes\n\n${bullet}\n`);
+ expect(out).toBe(`### Minor Changes\n\n${bullet}\n`);
+ });
+
+ test('keeps multiple bullets within a single beta section', () => {
+ const input = '### Patch Changes\n\n- First patch\n\n- Second patch\n\n- Third patch\n';
+ expect(aggregateStableChangelog(input)).toBe(
+ '### Patch Changes\n\n- First patch\n\n- Second patch\n\n- Third patch\n',
+ );
+ });
+
+ test('tolerates h2 and h4 level headings (upstream heading-level drift)', () => {
+ const input = '## Minor Changes\n\n- via h2\n\n#### Patch Changes\n\n- via h4\n';
+ expect(aggregateStableChangelog(input)).toBe(
+ '### Minor Changes\n\n- via h2\n\n### Patch Changes\n\n- via h4\n',
+ );
+ });
+
+ test('empty input yields empty output (no headings emitted for absent levels)', () => {
+ expect(aggregateStableChangelog('')).toBe('');
+ expect(aggregateStableChangelog('\n\n')).toBe('');
+ });
+});