Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Document that each pull request lands on master as one commit titled with its title (#9381)

Garry Tan1842cb026700
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0cabeb8208..4f27f9421c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1619,7 +1619,7 @@ Reported and first fixed by @javieraldape (#9159).
- `src/core/engine-sql/chunks.ts`: with a signature, `sumStaleChunkChars` sums disjoint unembedded and drifted arms through UNION ALL, so the partial stale index serves the common case (measured 100 ms to 12 ms on a 200k-chunk fixture with no drift); totals are unchanged. Reported and first fixed by @Masashi-Ono0611 (#8811, supersedes #8813).
- `src/core/persistence/coordinator.ts`, `src/core/persistence/local-edit-adoption.ts`: adoption recovery gathers its landed-commit proof before the recovery transaction and rechecks HEAD and the request's pin under the row lock, staying `recovery_required` on any change. Reported and first fixed by @javieraldape (#8869, supersedes #8914).
- `src/commands/extract.ts`: sync's inline timeline extraction writes each page's rows through one batch projection (same trust gate and dedup), falls back to row-by-row only when the batch fails, and counts rows actually inserted. A missing or soft-deleted page still fails its slug with `PageMissingError`, checked under a page lock inside the batch transaction. Reported and first fixed by @troyhoffman-oss (supersedes #6805).
-- `src/core/shared-skills/migration-export.ts`: an exported or inventory-stage checkpoint with no bound source and no started topology claim can move to a new root, restarting at inventory with a fresh request; a bound or claimed checkpoint still refuses. A root refused for sitting inside a Git worktree is now checked before anything is staged, so no copy of the export is left in the repository; an earlier staging directory is removed only when it holds exactly the export's own files, and an earlier filled root is listed in the receipt (`earlier_roots`) and the printed next steps. Reported and first fixed by @Masashi-Ono0611 (#8528, supersedes #8628).
+- `src/core/shared-skills/migration-export.ts`: an exported or inventory-stage checkpoint with no bound source and no started topology claim can move to a new root, restarting at inventory with a fresh request; a bound or claimed checkpoint still refuses. A root refused for sitting inside a Git worktree is now checked before anything is staged, so no copy of the export is left in the repository; an earlier staging directory is removed only when it holds exactly the export's own files, and an earlier filled root is listed in the receipt (`earlier_roots`) and the printed next steps. Reported by @narco (#8528); first fixed by @Masashi-Ono0611 (supersedes #8628).
- `src/core/shared-skills/setup.ts`: `installPackagedSharedSkills` resumes the caller's open or committed default-pack publication in the same source incarnation instead of submitting a second one. Reported and first fixed by @javieraldape (#8453, supersedes #8493).
- Docs: key-files entries. `scripts/structural-suites.tsv` regenerated.
- Tests: `test/connection-manager.serial.test.ts`, `test/e2e/engine-open-postgres.test.ts`, `test/postgres-deadline-read.test.ts`, `test/e2e/persistence-preparation-pool-wait-postgres.test.ts`, `test/pg-type-cache.test.ts`, `test/sum-stale-chunk-chars-8811.test.ts` (PGLite and Postgres), `test/adopt-local-edit.test.ts`, `test/extract-timeline-for-slugs-batch.test.ts`, `test/shared-skills-export.serial.test.ts`, `test/shared-skills-packaged-key-7734.test.ts`.
diff --git a/changelog.d/capy-contributor-gate-wording-agent-filed-label.md b/changelog.d/capy-contributor-gate-wording-agent-filed-label.md
new file mode 100644
index 0000000000..56fc314438
--- /dev/null
+++ b/changelog.d/capy-contributor-gate-wording-agent-filed-label.md
@@ -0,0 +1,9 @@
+**Outside contributors now get an accurate picture of what happens to their pull requests, and issues our own automation files are labelled so community reports are easy to find.** The comment posted on an outside pull request and the new "How an outside pull request is handled" section of CONTRIBUTING.md describe what really happens: docs-only changes can be merged as they are after a read, small plainly correct fixes are rebuilt with credit to the author, every PR lands as one squashed commit with outside authors credited by a `Co-authored-by:` trailer, and the three-open-PR limit never applies to anyone who had a PR taken in the last 90 days. Every issue the repo's scripts and CI open now carries the `agent-filed` label, and the new-issue page links to a "Community issues" search that leaves those out.
+
+### Itemized changes
+
+- `scripts/fix-wave-gate.ts`, `scripts/fix-wave-closeout.ts`: the gate and close-out comments describe the current rules and link to the new CONTRIBUTING section.
+- `scripts/lib/gh-issue.ts`: `createIssue` always adds `agent-filed`; `scripts/upgrade-matrix.ts` and `scripts/lib/master-red.ts` keep it on every issue they open.
+- `.github/ISSUE_TEMPLATE/config.yml`: a "Community issues" contact link.
+- Docs: CONTRIBUTING.md, README.md, docs/RELEASING.md and the CI key-files page.
+- Tests: new `test/scripts/gh-issue-agent-filed.test.ts`; the nightly-issue, fix-wave-gate and fix-wave-closeout tests updated.
diff --git a/changelog.d/capy-squash-landing.md b/changelog.d/capy-squash-landing.md
new file mode 100644
index 0000000000..8428fd9696
--- /dev/null
+++ b/changelog.d/capy-squash-landing.md
@@ -0,0 +1,6 @@
+**docs/RELEASING.md now says how a pull request lands on master: as one commit titled with the pull request's title and number.**
+
+### Changed
+
+- docs/RELEASING.md, "Releases per batch", has a "How a PR lands" paragraph: each pull request, release pull requests included, lands as one squashed commit whose subject is its title followed by `(#<number>)`, with other authors credited by `Co-authored-by:` trailers, while branches keep bringing master in with merge commits and are never rebased.
+- The contributor audit's offline fixture now includes a squashed `(#<number>)` commit next to its "Merge pull request" merges, so the audit's tests cover both commit shapes it reads.
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
index 7928bbaf8f..94858ca4bc 100644
--- a/docs/RELEASING.md
+++ b/docs/RELEASING.md
@@ -142,6 +142,18 @@ master since the last release one version and writes all the stamps at once.
`.gstack/ship-policy.json` turns this on (`changelog_fragments`,
`merge: "direct"`), and gstack's /ship, receipt and land commands follow it.
+**How a PR lands.** Every PR, release PRs included, lands on master as one
+squashed commit whose subject is the PR title followed by `(#<number>)`, so
+`git log --oneline master` reads as a list of changes, with no
+"Merge pull request" lines and none of a branch's own housekeeping commits.
+The maintainer's merge step makes that commit; its body is the PR's
+summary lines, and everyone else who wrote commits on the branch is
+credited with a `Co-authored-by:` trailer. Only the landing squashes. A
+branch brings master in with a merge commit and is never rebased or
+force-pushed; `history: "merge-only"` in `.gstack/ship-policy.json` makes
+/ship refuse a plan that would. Write the PR title as the one line a
+reader of the log should see.
+
**What a PR carries.**
- `changelog.d/<branch-slug>.md`: the PR's CHANGELOG entry with no version
diff --git a/scripts/contributor-audit-fixture.ts b/scripts/contributor-audit-fixture.ts
index fe8c4589aa..444f29ecac 100644
--- a/scripts/contributor-audit-fixture.ts
+++ b/scripts/contributor-audit-fixture.ts
@@ -5,8 +5,8 @@
*
* bun scripts/contributor-audit-fixture.ts <empty-dir>
*
- * The range <base>..<head> holds six merges, each a shape the audit must tell
- * apart, plus one open PR that conflicts with head:
+ * The range <base>..<head> holds six landed PRs (five merges, one squash), each
+ * a shape the audit must tell apart, plus one open PR that conflicts with head:
*
* #101 fix clamp product fix + a test that pins it → discriminates
* #102 greet suffix product change + a test that never calls it → does_not_discriminate
@@ -15,6 +15,8 @@
* #106 score note a comment + a test that only #107 makes green → does_not_discriminate
* (a whole-file revert would also drop #107's fix and call it discriminating)
* #107 fix score product fix, no test change → not_audited (no_tests)
+ * (landed as one squashed `Fix score (#107)` commit, the shape
+ * master's PRs land in; the others are "Merge pull request" merges)
* PR #105 rewrites the clamp line #101 fixed → conflict
*
* No package.json, so nothing installs and nothing touches the network.
@@ -32,12 +34,17 @@ export function buildFixture(dir: string): Fixture {
const write = (rel: string, body: string) => { mkdirSync(dirname(join(dir, rel)), { recursive: true }); writeFileSync(join(dir, rel), body); };
const as = (who: string) => { git('config', 'user.name', who); git('config', 'user.email', `${who}@example.invalid`); };
const commit = (msg: string) => { git('add', '-A'); git('commit', '-qm', msg); };
- const mergePr = (n: number, branch: string, who: string, change: () => void) => {
+ const mergePr = (n: number, branch: string, who: string, change: () => void, squashTitle?: string) => {
git('checkout', '-qb', branch, 'master');
as(who);
change();
commit(`${branch}: contributor change`);
git('checkout', '-q', 'master');
+ if (squashTitle) {
+ git('merge', '-q', '--squash', branch);
+ git('commit', '-qm', `${squashTitle} (#${n})`);
+ return;
+ }
as('maintainer-example');
git('merge', '-q', '--no-ff', branch, '-m', `Merge pull request #${n} from ${who}/${branch}`);
};
@@ -71,7 +78,7 @@ export function buildFixture(dir: string): Fixture {
write('src/score.ts', SCORE);
write('test/score.test.ts', "import { expect, test } from 'bun:test';\nimport { score } from '../src/score';\n\ntest('scores two', () => {\n expect(score()).toBe(2);\n});\n");
});
- mergePr(107, 'fix-score', 'hana-example', () => write('src/score.ts', SCORE.replace('return 0;', 'return a + b;')));
+ mergePr(107, 'fix-score', 'hana-example', () => write('src/score.ts', SCORE.replace('return 0;', 'return a + b;')), 'Fix score');
const head = git('rev-parse', 'HEAD');
git('checkout', '-qb', 'pr-105', base);
diff --git a/test/scripts/contributor-audit.test.ts b/test/scripts/contributor-audit.test.ts
index 3c511e591b..120703ad50 100644
--- a/test/scripts/contributor-audit.test.ts
+++ b/test/scripts/contributor-audit.test.ts
@@ -45,7 +45,7 @@ describe('contributor audit on the fixture range', () => {
expect(byPr[103]).toMatchObject({ result: 'setup_failed', reason: 'baseline_red' });
expect(byPr[104]).toMatchObject({ result: 'not_audited', reason: 'no_product_change' });
expect(byPr[106]).toMatchObject({ result: 'does_not_discriminate', audited_at: f.head });
- expect(byPr[107]).toMatchObject({ result: 'not_audited', reason: 'no_tests' });
+ expect(byPr[107]).toMatchObject({ result: 'not_audited', reason: 'no_tests', subject: 'Fix score (#107)', author: 'hana-example' });
expect(byPr[105].result).toBe('conflict');
expect(byPr[105].reason).toContain('src/clamp.ts');
expect(report.exit_code).toBe(1);