From 9041465951d94fe9cebb5b2a12576d270052bd69 Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Mon, 3 Aug 2026 15:47:35 -0500 Subject: [PATCH 1/6] CLAUDE.md: comments should be concise, explained at first mention, and cross-reference with above/below Prompted by a review pass on PR #54's test-harness comments, which had drifted into unnecessary length and repetition. Two rules worth keeping for every future comment, not just that PR: humans have limited context too, so say the point in as few words as it needs; and a comment referencing another spot in the same file should say whether that spot is above or below, so the reader isn't left searching both directions. --- CLAUDE.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index d0c364c..ee1bfc7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -167,6 +167,14 @@ Always use block comment format for multi-line comments in SQL files: Never use `--` line comments for multi-line explanations. +Be concise — humans have limited context too, not just AI. Say the point in as few words +as it needs, not as many as the topic could support. + +Explain something at the *first* place it's mentioned, not somewhere later that assumes +context the reader hasn't reached yet (exceptions need a reason). When a comment points +to another spot in the same file, say `above` or `below` so the reader doesn't have to +search both directions. + ### Closing non-indentable blocks When closing a code block that cannot be indented to show its nesting (e.g. SQL `\endif`, `DO $$...$$`, shell heredocs, column-0 `fi`/`esac`) AND that block From aaa53325b364b4abd2837b45b3e85e62dba42da0 Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Mon, 3 Aug 2026 15:52:38 -0500 Subject: [PATCH 2/6] CLAUDE.md: prefer make over ci.yml for a new test-matrix dimension Distilled from PR #54's back-and-forth over where TEST_SCHEMA and the update-testing check should live: a make-level dimension runs locally and never costs a container/job, while a ci.yml-level one always does unless deliberately batched -- which is its own added complexity. The one real exception is when a dimension's whole point is isolation (pg_tle needing its own cluster), not just another combination to run. --- CLAUDE.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index ee1bfc7..b55479b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,6 +6,17 @@ After **every** push, monitor GitHub CI in a background subagent until all jobs (`.github/workflows/ci.yml`'s `changes` job computes the actual per-push changed file set and exposes `docs_only`; the heavy `test`, `pg-upgrade-test`, and `extension-update-test` jobs skip when `needs.changes.outputs.docs_only == 'true'` — i.e. every changed file in that push matches `**.md`/`**.asc`. Unlike the old workflow-level `paths-ignore`, this is evaluated per push/commit, not over the whole PR diff, so a doc-only commit on a PR that also touches code still gets the skip, and the workflow (including the required `all-checks-passed` check) always triggers and reports rather than being skipped outright by GitHub. When unsure, check `gh run list` for the pushed commit and monitor whatever run appears; if none does, there is nothing to watch.) +## Where a test-matrix dimension belongs + +The full set of things we test is itself a matrix (PostgreSQL major, update path, schema +targeting, pg_tle vs. filesystem, and — over time — more `make`-level test targets too). +When adding a new dimension, prefer putting it in `make` over `ci.yml` whenever that's +reasonable: it can then be run locally, and it never spins up an extra container/job. The +one reason to prefer `ci.yml` instead is when a dimension genuinely needs its own +isolated environment to mean anything (e.g. pg_tle's dedicated cluster, proving isolation +holds) — `ci.yml` *can* batch multiple checks into one job, but doing that on purpose adds +real complexity there, so default to `make` unless isolation is the actual point. + ## Build/test system (pgxntool) This repo's build is driven by pgxntool (embedded under `pgxntool/`). Its docs are From 758e2461876ce430647a9a9553ccbb4b04a281d1 Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Mon, 3 Aug 2026 16:41:55 -0500 Subject: [PATCH 3/6] CLAUDE.md: drop schema-targeting from the test-matrix-dimension example list It was never a valid example -- cat_tools' control file pins schema = 'cat_tools' with relocatable = false, so there's no schema dimension to put anywhere, in make or ci.yml. The general make-vs-ci.yml principle itself is unaffected; it just needed a real example in its place. --- CLAUDE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b55479b..35d9ace 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,9 +8,9 @@ After **every** push, monitor GitHub CI in a background subagent until all jobs ## Where a test-matrix dimension belongs -The full set of things we test is itself a matrix (PostgreSQL major, update path, schema -targeting, pg_tle vs. filesystem, and — over time — more `make`-level test targets too). -When adding a new dimension, prefer putting it in `make` over `ci.yml` whenever that's +The full set of things we test is itself a matrix (PostgreSQL major, update path, pg_tle +vs. filesystem, and — over time — more `make`-level test targets too). When adding a new +dimension, prefer putting it in `make` over `ci.yml` whenever that's reasonable: it can then be run locally, and it never spins up an extra container/job. The one reason to prefer `ci.yml` instead is when a dimension genuinely needs its own isolated environment to mean anything (e.g. pg_tle's dedicated cluster, proving isolation From d702762eb47a1189affa92e09f5a586799ce17ad Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Mon, 3 Aug 2026 16:43:50 -0500 Subject: [PATCH 4/6] CLAUDE.md: PR descriptions can be long, but need real structure Prompted directly by PR #54/#75 turning into hard-to-follow walls of text (a real contributor to a costly mid-PR mix-up), versus #74's own description staying easy to follow despite covering real backstory. Length past the opening isn't the problem -- an unstructured mass of prose is. --- CLAUDE.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 35d9ace..32984f4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -87,6 +87,10 @@ Write it accordingly: - Do NOT hard-wrap paragraphs: write each paragraph as a single long line (blank line between paragraphs). Hard-wrapping at ~80 columns conflicts with how GitHub builds the squash commit message from the description. +- Length past the opening is fine — backstory and detail are often worth keeping. Being + hard to *scan* is the actual problem: if there's enough detail to justify it, give the + rest real structure (headers, bullet lists, separate sections for "what changed" vs. + "how it was verified"), not one undifferentiated block of prose. ## SQL file conventions From 906a1bbca2d02dac88b9ad279d62c72122e131d6 Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Mon, 3 Aug 2026 17:19:19 -0500 Subject: [PATCH 5/6] CLAUDE.md: the first-mention rule isn't absolute Concrete exception worth naming: already mid-explanation of A, need to mention B (which also needs explaining) -- fully explaining B right there often confuses A's explanation more than deferring B would. --- CLAUDE.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 32984f4..f4329f2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -185,10 +185,13 @@ Never use `--` line comments for multi-line explanations. Be concise — humans have limited context too, not just AI. Say the point in as few words as it needs, not as many as the topic could support. -Explain something at the *first* place it's mentioned, not somewhere later that assumes -context the reader hasn't reached yet (exceptions need a reason). When a comment points -to another spot in the same file, say `above` or `below` so the reader doesn't have to -search both directions. +Usually, explain something at the *first* place it's mentioned, not somewhere later that +assumes context the reader hasn't reached yet — but this isn't absolute. One real +exception: you're already in the middle of explaining A, and need to mention B (which +also needs its own explanation) — stopping to fully explain B right there often confuses +the explanation of A more than deferring B to its own natural spot would. Use judgment. +When a comment points to another spot in the same file, say `above` or `below` so the +reader doesn't have to search both directions. ### Closing non-indentable blocks When closing a code block that cannot be indented to show its nesting (e.g. SQL From bd3410a61ec238cc8409591de02ee4447752a8d6 Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Mon, 3 Aug 2026 17:28:07 -0500 Subject: [PATCH 6/6] CLAUDE.md: stop over-enumerating examples, and call out verbosity/context-leak in PR descriptions Two fixes: the test-matrix-dimension example list didn't need full enumeration (an "etc." example works fine) and implied ci.yml would never grow, plus overstated isolation as the ONLY reason to prefer it -- it's a real tradeoff, just one to bias against by default. Separately, the PR-description structure rule covered organization but not plain wordiness or including discussion history that never resulted in merged code -- both worth calling out on their own. --- CLAUDE.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f4329f2..0a181e6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,14 +8,12 @@ After **every** push, monitor GitHub CI in a background subagent until all jobs ## Where a test-matrix dimension belongs -The full set of things we test is itself a matrix (PostgreSQL major, update path, pg_tle -vs. filesystem, and — over time — more `make`-level test targets too). When adding a new -dimension, prefer putting it in `make` over `ci.yml` whenever that's -reasonable: it can then be run locally, and it never spins up an extra container/job. The -one reason to prefer `ci.yml` instead is when a dimension genuinely needs its own -isolated environment to mean anything (e.g. pg_tle's dedicated cluster, proving isolation -holds) — `ci.yml` *can* batch multiple checks into one job, but doing that on purpose adds -real complexity there, so default to `make` unless isolation is the actual point. +The full set of things we test is itself a matrix (PostgreSQL major, UPDATE vs. CREATE +EXTENSION, etc.). It's a real tradeoff, not a rule with one exception — but bias toward +putting a new dimension in `make` over `ci.yml`: it can then be run locally, and it never +spins up an extra container/job. Needing real isolation to mean anything (e.g. pg_tle's +dedicated cluster) is one good reason to put a dimension in `ci.yml` instead, not the only +possible one — weigh the actual tradeoff, just start from a bias toward `make`. ## Build/test system (pgxntool) @@ -91,6 +89,11 @@ Write it accordingly: hard to *scan* is the actual problem: if there's enough detail to justify it, give the rest real structure (headers, bullet lists, separate sections for "what changed" vs. "how it was verified"), not one undifferentiated block of prose. +- Watch for two habits specifically: being more verbose than the point actually needs — + structure alone doesn't fix over-length — and "leaking" context from how the work + evolved. An earlier idea that got revised or dropped before anything merged describes + the process, not the result; it doesn't belong in the description of what actually + shipped. ## SQL file conventions