Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Published release notes open with one line per change and its pull request (GST-2799) (#9445)

Garry Tan772872bfbe35
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 2ac5d4bb21..6f103c5d78 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -236,6 +236,9 @@ jobs:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
ref: ${{ needs.ci-gate.outputs.sha }}
+ # Full history and tags: the notes list reads the fragments every
+ # release commit since the previous v* tag folded.
+ fetch-depth: 0
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
with:
path: artifacts
@@ -250,7 +253,7 @@ jobs:
RELEASE_VERSION: ${{ needs.version.outputs.version }}
run: |
v="$RELEASE_VERSION"
- if ! bash scripts/changelog-entry.sh "$v" > /tmp/release-notes.md || ! [ -s /tmp/release-notes.md ]; then
+ if ! bash scripts/changelog-entry.sh --pr-list "$v" > /tmp/release-notes.md || ! [ -s /tmp/release-notes.md ]; then
echo "See [CHANGELOG.md](https://github.com/${GITHUB_REPOSITORY}/blob/master/CHANGELOG.md) for v$v." > /tmp/release-notes.md
fi
# A re-run that repairs a half-published release republishes it as a
diff --git a/changelog.d/README.md b/changelog.d/README.md
index c575f27afb..688e1d1c83 100644
--- a/changelog.d/README.md
+++ b/changelog.d/README.md
@@ -2,7 +2,11 @@
One file per PR: the PR's CHANGELOG entry, without a version heading. gstack
`/ship` writes it as `changelog.d/<branch-slug>.md`; nobody edits VERSION,
-the package.json version or CHANGELOG.md in a PR.
+the package.json version or CHANGELOG.md in a PR. Every PR needs one, a
+tests-only PR included: the release folds only fragments, so a change without
+one is missing from the release notes, and a release with nothing to fold is
+refused. The fragment's first bold line becomes that change's line at the top
+of the GitHub release notes.
```markdown
**What changed, in one sentence.**
diff --git a/changelog.d/release-notes-pr-list.md b/changelog.d/release-notes-pr-list.md
new file mode 100644
index 0000000000..5a3947c937
--- /dev/null
+++ b/changelog.d/release-notes-pr-list.md
@@ -0,0 +1,6 @@
+**Published release notes now open with one line per change and the pull request that made it.**
+
+### Changed
+- The release workflow puts a list at the top of each GitHub release: one line per change the release folds, taken from the change's changelog entry, with its pull request number. A release that never published is listed in the next one. CHANGELOG.md is unchanged.
+- `bun run verify` fails when a test reads a `changelog.d` file from the repository, because the next release deletes that file and the test breaks.
+- `changelog.d/README.md` says every pull request needs a changelog entry, a tests-only one included.
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
index 0b55ece698..18cee3d629 100644
--- a/docs/RELEASING.md
+++ b/docs/RELEASING.md
@@ -642,9 +642,10 @@ If any SHA differs from what's in the workflow files, update the pin and version
`VERSION`, plus `workflow_dispatch` for a manual first run or repair). No
manual tag push is part of the ship flow — the workflow reads `VERSION` (the
single source of truth), mints tag `v<VERSION>` at the pushed commit, titles
-the release the same, uses that version's `CHANGELOG.md` entry as the notes
-(`scripts/changelog-entry.sh`; falls back to a CHANGELOG link if the entry is
-missing), and attaches the compiled binaries. Every one is published as a
+the release the same, uses that version's `CHANGELOG.md` entry as the notes,
+opened by one line per folded changelog fragment with the pull request that
+added it (`scripts/changelog-entry.sh --pr-list`; falls back to a CHANGELOG
+link if the entry is missing), and attaches the compiled binaries. Every one is published as a
pre-release; only the stable release is GitHub's "Latest" ([Which release GitHub
calls Latest](#which-release-github-calls-latest)).
diff --git a/package.json b/package.json
index 83f5cdadfd..2f84ab0cf4 100644
--- a/package.json
+++ b/package.json
@@ -130,6 +130,7 @@
"check:skills-manifest": "bash scripts/check-skills-manifest-fresh.sh",
"check:skills-lock-history": "bun scripts/check-skills-lock-history.ts",
"check:test-names": "bash scripts/check-test-real-names.sh",
+ "check:test-fragment-reads": "bash scripts/check-test-fragment-reads.sh",
"check:progress": "bash scripts/check-progress-to-stdout.sh",
"check:no-tracked-symlinks": "bash scripts/check-no-tracked-symlinks.sh",
"check:admin-build": "bash scripts/check-admin-build.sh",
diff --git a/scripts/changelog-entry.sh b/scripts/changelog-entry.sh
index 4f407b8e97..a22b9bacd5 100755
--- a/scripts/changelog-entry.sh
+++ b/scripts/changelog-entry.sh
@@ -4,18 +4,66 @@
# .github/workflows/release.yml as the GitHub release notes; tested by
# test/release-workflow.test.ts.
#
-# Usage: changelog-entry.sh <version> [changelog-file]
+# With --pr-list, run in a git checkout of the release commit, the body opens
+# with one line per change: for every changelog.d fragment a release commit
+# deleted since the newest v* tag before HEAD, in fold order (oldest release
+# first, then path order), the fragment's first bold line plus the "(#N)" of
+# the master commit that added it. The list goes on the GitHub release only;
+# CHANGELOG.md never carries it.
+#
+# Usage: changelog-entry.sh [--pr-list] <version> [changelog-file]
# Exits 1 when the version has no entry (caller falls back to a link stub).
set -euo pipefail
-ver="${1:?usage: changelog-entry.sh <version> [changelog-file]}"
+pr_list=0
+if [ "${1:-}" = "--pr-list" ]; then pr_list=1; shift; fi
+ver="${1:?usage: changelog-entry.sh [--pr-list] <version> [changelog-file]}"
file="${2:-CHANGELOG.md}"
# Exact-string prefix match on "## [<ver>]" — no regex, so dots in the
# version can't glob and a 3-segment version can't match a 4-segment header.
-awk -v ver="$ver" '
- index($0, "## [" ver "]") == 1 { found = 1; next }
- found && /^## \[/ { exit }
- found { print }
- END { exit found ? 0 : 1 }
-' "$file"
+entry() {
+ awk -v ver="$ver" '
+ index($0, "## [" ver "]") == 1 { found = 1; next }
+ found && /^## \[/ { exit }
+ found { print }
+ END { exit found ? 0 : 1 }
+ ' "$file"
+}
+
+# One "- <headline> (#N)" line per folded fragment. Prints nothing when there is
+# no earlier release tag or no history (a shallow checkout).
+list_changes() {
+ local prev release path headline subject pr
+ prev="$(git describe --tags --abbrev=0 --match 'v[0-9]*' HEAD^ 2>/dev/null)" || return 0
+ for release in $(git log --reverse --first-parent --format=%H "$prev..HEAD" -- VERSION); do
+ while IFS= read -r path; do
+ case "$path" in changelog.d/*.md) ;; *) continue ;; esac
+ [ "$path" = "changelog.d/README.md" ] && continue
+ headline="$(git show "$release^:$path" | awk '
+ NR == 1 && /^---[[:space:]]*$/ { fm = 1; next }
+ fm { if (/^---[[:space:]]*$/) fm = 0; next }
+ /^\*\*/ { sub(/^\*\*/, ""); sub(/\*\*[[:space:]]*$/, ""); print; exit }
+ ')"
+ [ -n "$headline" ] || continue
+ subject="$(git log --first-parent --diff-filter=A --format=%s -1 "$release^" -- "$path")"
+ pr="$(printf '%s\n' "$subject" | sed -nE 's/.*\(#([0-9]+)\)[[:space:]]*$/\1/p; s/^Merge pull request #([0-9]+).*/\1/p' | head -n1)"
+ headline="${headline%.}"
+ cited="$(printf '%s\n' "$headline" | sed -nE 's/.*[[:space:]]\((#[0-9]+(, #[0-9]+)*)\)$/\1/p')"
+ if [ -n "$cited" ]; then headline="${headline% ("$cited")}"; fi
+ if [ -n "$pr" ] && [[ ", $cited, " != *", #$pr, "* ]]; then cited="${cited:+$cited, }#$pr"; fi
+ if [ -n "$cited" ]; then
+ printf -- '- %s (%s)\n' "$headline" "$cited"
+ else
+ printf -- '- %s\n' "$headline"
+ fi
+ done < <(git diff-tree --no-commit-id -r --diff-filter=D --name-only "$release^" "$release" -- changelog.d | LC_ALL=C sort)
+ done
+}
+
+entry > /dev/null
+if [ "$pr_list" = 1 ]; then
+ list="$(list_changes)"
+ if [ -n "$list" ]; then printf '%s\n\n' "$list"; fi
+fi
+entry
diff --git a/scripts/check-test-fragment-reads.sh b/scripts/check-test-fragment-reads.sh
new file mode 100755
index 0000000000..6ce21fb245
--- /dev/null
+++ b/scripts/check-test-fragment-reads.sh
@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Fail when a test reads a named changelog.d fragment from the repository.
+#
+# A release folds every changelog.d/<fragment>.md into CHANGELOG.md and deletes
+# it, so a test that opens one by name passes on its PR and fails on the release
+# commit (v0.60.726.0 never published for this). Read CHANGELOG.md, or build the
+# fragment in a temporary fixture directory, instead.
+#
+# A line counts when it names changelog.d, a .md file other than README.md and
+# the repository root (ROOT, REPO, REPO_ROOT, import.meta.dir, __dirname or
+# process.cwd()). Fixture paths built under a temporary directory don't.
+# Seam: GBRAIN_GUARD_ROOT (fixture tree root, used by scripts/guard-self-test.sh).
+set -euo pipefail
+
+cd "${GBRAIN_GUARD_ROOT:-$(dirname "$0")/..}"
+
+hits="$(grep -rnE --exclude-dir=guards 'changelog\.d' test/ \
+ | grep -E '[A-Za-z0-9_.-]+\.md' \
+ | grep -vE "changelog\.d['\"/, ]+README\.md" \
+ | grep -E '\b(ROOT|REPO|REPO_ROOT)\b|import\.meta\.dir|__dirname|process\.cwd\(\)' || true)"
+
+if [ -n "$hits" ]; then
+ echo "FAIL: a test reads a changelog.d fragment from the repository; the next release deletes it and the test breaks:"
+ echo "$hits"
+ echo "Fix: read the entry from CHANGELOG.md (it holds the text once the release folds it), or write the fragment into a temporary fixture."
+ exit 1
+fi
+echo "OK: no test reads a changelog.d fragment from the repository."
diff --git a/scripts/guards-manifest.tsv b/scripts/guards-manifest.tsv
index 2083f54d2d..6b6cd424c7 100644
--- a/scripts/guards-manifest.tsv
+++ b/scripts/guards-manifest.tsv
@@ -39,6 +39,7 @@ check-source-scope-onboard.sh scanner yes onboard SQL sites need source_id scopi
check-synthetic-corpus-privacy.sh scanner todo
check-system-of-record.sh scanner todo
check-test-real-names.sh scanner todo
+check-test-fragment-reads.sh scanner yes a test that reads a named changelog.d fragment from the repo root breaks on the release commit that folds it (v0.60.726.0); fixture trees under test/fixtures/guards/ are skipped; GBRAIN_GUARD_ROOT seam; bad-template fixture covers the template-string path
check-worker-lock-renewal-shape.sh scanner todo
check-worker-pool-atomicity.sh scanner todo
check-gateway-routed-no-direct-anthropic.sh scanner yes no runtime @anthropic-ai/sdk import or new Anthropic() in gateway-routed files; GBRAIN_GUARD_ROOT seam
diff --git a/scripts/run-verify-parallel.sh b/scripts/run-verify-parallel.sh
index 363927f019..e2c86c926e 100755
--- a/scripts/run-verify-parallel.sh
+++ b/scripts/run-verify-parallel.sh
@@ -113,6 +113,8 @@ CHECKS=(
"check:resolver"
"check:privacy"
"check:test-names"
+ # A test that opens a changelog.d fragment by name breaks on the release commit.
+ "check:test-fragment-reads"
"check:test-isolation"
# D7: a test that gates execution on a GBRAIN_* opt-in the operator-env
# preload strips is a silent skip; TS AST scan, ~2s.
diff --git a/test/fixtures/guards/check-test-fragment-reads.sh/bad-template/test/notice.test.ts.txt b/test/fixtures/guards/check-test-fragment-reads.sh/bad-template/test/notice.test.ts.txt
new file mode 100644
index 0000000000..d6425c07f0
--- /dev/null
+++ b/test/fixtures/guards/check-test-fragment-reads.sh/bad-template/test/notice.test.ts.txt
@@ -0,0 +1 @@
+const entry = readFileSync(`${REPO_ROOT}/changelog.d/feature-x.md`, 'utf8');
diff --git a/test/fixtures/guards/check-test-fragment-reads.sh/bad/test/notice.test.ts.txt b/test/fixtures/guards/check-test-fragment-reads.sh/bad/test/notice.test.ts.txt
new file mode 100644
index 0000000000..dd389951cd
--- /dev/null
+++ b/test/fixtures/guards/check-test-fragment-reads.sh/bad/test/notice.test.ts.txt
@@ -0,0 +1 @@
+const entry = readFileSync(join(ROOT, 'changelog.d', 'feature-x.md'), 'utf8');
diff --git a/test/fixtures/guards/check-test-fragment-reads.sh/good/test/notice.test.ts.txt b/test/fixtures/guards/check-test-fragment-reads.sh/good/test/notice.test.ts.txt
new file mode 100644
index 0000000000..ca9eac6251
--- /dev/null
+++ b/test/fixtures/guards/check-test-fragment-reads.sh/good/test/notice.test.ts.txt
@@ -0,0 +1,3 @@
+const entry = readFileSync(join(ROOT, 'CHANGELOG.md'), 'utf8');
+const readme = readFileSync(join(ROOT, 'changelog.d', 'README.md'), 'utf8');
+put(root, { 'changelog.d/feature-x.md': '**Faster sync.**\n' });
diff --git a/test/release-workflow.test.ts b/test/release-workflow.test.ts
index 4408678362..3abe16745f 100644
--- a/test/release-workflow.test.ts
+++ b/test/release-workflow.test.ts
@@ -9,9 +9,9 @@
*/
import { describe, expect, test } from 'bun:test';
import { execFileSync } from 'node:child_process';
-import { mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
import { EXPECTED_BUILDER_IDS, expectedAssetName } from '../src/core/binary-self-update.ts';
const ROOT = join(import.meta.dir, '..');
@@ -193,6 +193,75 @@ Release summary line.
});
});
+describe('scripts/changelog-entry.sh --pr-list', () => {
+ function git(cwd: string, ...args: string[]): string {
+ return execFileSync('git', args, { cwd, encoding: 'utf-8' });
+ }
+ function commit(repo: string, subject: string, files: Record<string, string | null>): void {
+ for (const [path, text] of Object.entries(files)) {
+ if (text === null) git(repo, 'rm', '-q', path);
+ else {
+ mkdirSync(join(repo, dirname(path)), { recursive: true });
+ writeFileSync(join(repo, path), text);
+ git(repo, 'add', path);
+ }
+ }
+ git(repo, 'commit', '-q', '-m', subject);
+ }
+ const section = (v: string, body: string) => `# Changelog\n\n## [${v}] - 2026-11-15\n\n${body}\n`;
+ function fixture(): string {
+ const repo = mkdtempSync(join(tmpdir(), 'gbrain-prlist-'));
+ git(repo, 'init', '-q', '-b', 'master');
+ git(repo, 'config', 'user.email', '[email protected]');
+ git(repo, 'config', 'user.name', 't');
+ git(repo, 'config', 'commit.gpgsign', 'false');
+ commit(repo, 'v0.1.0.0 release (#1)', { VERSION: '0.1.0.0\n', 'CHANGELOG.md': section('0.1.0.0', 'First.'), 'changelog.d/README.md': 'How fragments work.\n' });
+ git(repo, 'tag', 'v0.1.0.0');
+ commit(repo, 'Sync is faster (#11)', { 'changelog.d/b-beta.md': '**Sync is faster.**\n\n### Changed\n- beta\n' });
+ commit(repo, 'Search finds old pages again (#12)', { 'changelog.d/a-alpha.md': '---\nimportant: regression\n---\n**Search finds old pages again (#12).**\n\n### Fixed\n- alpha\n' });
+ return repo;
+ }
+ function run(repo: string, ...args: string[]): string {
+ return execFileSync('bash', [join(ROOT, 'scripts/changelog-entry.sh'), ...args], { cwd: repo, encoding: 'utf-8' });
+ }
+
+ test('opens the body with one line per folded fragment, in fold order, each with the PR that added it', () => {
+ const repo = fixture();
+ try {
+ commit(repo, 'v0.1.1.0 release (#13)', { VERSION: '0.1.1.0\n', 'CHANGELOG.md': section('0.1.1.0', 'Folded text.'), 'changelog.d/a-alpha.md': null, 'changelog.d/b-beta.md': null });
+ expect(run(repo, '--pr-list', '0.1.1.0')).toBe('- Search finds old pages again (#12)\n- Sync is faster (#11)\n\n\nFolded text.\n');
+ expect(run(repo, '0.1.1.0')).toBe('\nFolded text.\n');
+ } finally {
+ rmSync(repo, { recursive: true, force: true });
+ }
+ });
+
+ test('a release that never published is listed in the next one, a commit with no PR number gets a bare line, and a headline that cites another PR prints every number once in one bracket', () => {
+ const repo = fixture();
+ try {
+ commit(repo, 'v0.1.1.0 release (#13)', { VERSION: '0.1.1.0\n', 'CHANGELOG.md': section('0.1.1.0', 'Unpublished.'), 'changelog.d/a-alpha.md': null, 'changelog.d/b-beta.md': null });
+ commit(repo, 'Direct fix', { 'changelog.d/c-gamma.md': '**The test passes after a release.**\n' });
+ commit(repo, 'Note the test fix (#14)', { 'changelog.d/d-delta.md': '**The notice test keeps passing after a release (#9).**\n' });
+ commit(repo, 'v0.1.2.0 release (#15)', { VERSION: '0.1.2.0\n', 'CHANGELOG.md': section('0.1.2.0', 'Second.'), 'changelog.d/c-gamma.md': null, 'changelog.d/d-delta.md': null });
+ expect(run(repo, '--pr-list', '0.1.2.0')).toBe('- Search finds old pages again (#12)\n- Sync is faster (#11)\n- The test passes after a release\n- The notice test keeps passing after a release (#9, #14)\n\n\nSecond.\n');
+ } finally {
+ rmSync(repo, { recursive: true, force: true });
+ }
+ });
+
+ test('with no earlier release tag the body is the plain entry', () => {
+ const repo = fixture();
+ try {
+ git(repo, 'tag', '-d', 'v0.1.0.0');
+ commit(repo, 'v0.1.1.0 release (#13)', { VERSION: '0.1.1.0\n', 'CHANGELOG.md': section('0.1.1.0', 'Folded text.'), 'changelog.d/a-alpha.md': null, 'changelog.d/b-beta.md': null });
+ expect(run(repo, '--pr-list', '0.1.1.0')).toBe('\nFolded text.\n');
+ expect(() => run(repo, '--pr-list', '9.9.9.9')).toThrow();
+ } finally {
+ rmSync(repo, { recursive: true, force: true });
+ }
+ });
+});
+
describe('release.yml publish-template skip is visible (D-10)', () => {
test('an empty TEMPLATE_REPO_PAT warns with the owner-only fix and writes a step summary', async () => {
const { load } = await import('js-yaml');
diff --git a/test/upgrade-transcript-archive-notice.test.ts b/test/upgrade-transcript-archive-notice.test.ts
index 2a25663b3d..1a9f1a932f 100644
--- a/test/upgrade-transcript-archive-notice.test.ts
+++ b/test/upgrade-transcript-archive-notice.test.ts
@@ -6,8 +6,8 @@
*
* Before a release dates the row, the test adds it to the loaded table for the duration of the file (dated at the
* newest disclosed release, so the notice id is unchanged) and removes it afterwards; once a release has dated it, the
- * table already holds it and the test adds nothing. The release also folds the changelog fragment into CHANGELOG.md,
- * so the marker is read from whichever of the two holds it.
+ * table already holds it and the test adds nothing. The marker is read from CHANGELOG.md, where v0.60.726.0 folded the
+ * changelog fragment.
*/
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
@@ -61,12 +61,7 @@ describe('the conversation archive upgrade notice', () => {
expect(text.length).toBeLessThanOrEqual(2000);
expect(text).not.toContain('\n');
for (const phrase of ['gbrain transcripts archive off', 'conversations', 'gbrain embed --held --dry-run', 'keyless', 'gbrain transcripts archive on']) expect(text).toContain(phrase);
- let entry: string;
- try {
- entry = readFileSync(join(ROOT, 'changelog.d', 'transcript-archive-default.md'), 'utf8');
- } catch {
- entry = readFileSync(join(ROOT, 'CHANGELOG.md'), 'utf8');
- }
+ const entry = readFileSync(join(ROOT, 'CHANGELOG.md'), 'utf8');
expect(entry).toContain('<!-- behavior-change: ' + ID + ' -->');
});