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.ymlindex 2ac5d4bb21..6f103c5d78 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -236,6 +236,9 @@ jobs:- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4with: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 # v4with: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 ]; thenecho "See [CHANGELOG.md](https://github.com/${GITHUB_REPOSITORY}/blob/master/CHANGELOG.md) for v$v." > /tmp/release-notes.mdfi# A re-run that repairs a half-published release republishes it as adiff --git a/changelog.d/README.md b/changelog.d/README.mdindex 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.mdnew file mode 100644index 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.mdindex 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). Nomanual tag push is part of the ship flow — the workflow reads `VERSION` (thesingle 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 apre-release; only the stable release is GitHub's "Latest" ([Which release GitHubcalls Latest](#which-release-github-calls-latest)).diff --git a/package.json b/package.jsonindex 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.shindex 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+entrydiff --git a/scripts/check-test-fragment-reads.sh b/scripts/check-test-fragment-reads.shnew file mode 100755index 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.tsvindex 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 scopicheck-synthetic-corpus-privacy.sh scanner todocheck-system-of-record.sh scanner todocheck-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 pathcheck-worker-lock-renewal-shape.sh scanner todocheck-worker-pool-atomicity.sh scanner todocheck-gateway-routed-no-direct-anthropic.sh scanner yes no runtime @anthropic-ai/sdk import or new Anthropic() in gateway-routed files; GBRAIN_GUARD_ROOT seamdiff --git a/scripts/run-verify-parallel.sh b/scripts/run-verify-parallel.shindex 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.txtnew file mode 100644index 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.txtnew file mode 100644index 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.txtnew file mode 100644index 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.tsindex 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.tsindex 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 + ' -->');});