From 6716a8cc425de7b7c7cbbd0b9b2f97797be7aa2e Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Fri, 31 Jul 2026 17:34:18 -0500 Subject: [PATCH 1/4] CLAUDE.md: fix pre-existing documentation-accuracy errors Found during 2.3.0 release-prep API-documentation audit; unrelated to any code change in that release. - make test: correct the 'ensures' bullet list to reflect actual behavior (testdeps -> install -> installcheck -> diffs shown), and note that make test intentionally does NOT depend on clean (base.mk already documents this; README.asc already stated it correctly). - Two-Phase Build System: fix misattribution of which script generates which variables. meta.mk.sh only emits PGXN/PGXNVERSION into meta.mk; EXTENSIONS, EXTENSION_*_VERSION, and EXTENSION__CURRENT_VERSION__FILES are generated by control.mk.sh from .control files into control.mk, not by meta.mk.sh from META.json. Split into Phase 2 (meta.mk.sh) and Phase 3 (control.mk.sh) to match reality. - build_meta.sh: correct overstated claim that it strips X_comment fields; it only strips lines with an empty string value, which incidentally removes some (not all) X_comment placeholder lines. - Distribution Packaging: fix 'always creates git tag' -- make tag skips creating the tag when it already exists at HEAD. - Scripts section: replace the stale, hand-maintained list (missing pgxntool-sync.sh, update-setup-files.sh, pgtle.sh, control.mk.sh) with a pointer to each script's own header comment, which already documents its purpose. README.asc: note that pgxntool-sync also verifies (and recreates if missing) the test/pgxntool symlink, not just the setup.sh-copied files. Co-Authored-By: Claude --- CLAUDE.md | 38 +++++++++++++++++++++++--------------- README.asc | 2 +- 2 files changed, 24 insertions(+), 16 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 0b0e23e..c4fa466 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -91,18 +91,24 @@ include pgxntool/base.mk ### Phase 1: Meta Generation (`build_meta.sh`) - Processes `META.in.json` (template with placeholders/empty values) -- Strips out X_comment fields and empty values +- Strips lines with empty string values (this incidentally removes some, but not all, `X_comment` placeholder lines) - Produces clean `META.json` -### Phase 2: Variable Extraction (`meta.mk.sh`) -- Parses `META.json` using `JSON.sh` (a bash-based JSON parser) +### Phase 2: Distribution Variable Extraction (`meta.mk.sh`) +- Parses `META.json` (PGXN distribution metadata) - Generates `meta.mk` with Make variables: - `PGXN` - distribution name - `PGXNVERSION` - version number +- `base.mk` includes `meta.mk` via `-include` + +### Phase 3: Extension Variable Extraction (`control.mk.sh`) +- Parses each `.control` file (what PostgreSQL actually uses), not `META.json` +- Generates `control.mk` with Make variables and rules: - `EXTENSIONS` - list of extensions provided - - `EXTENSION_*_VERSION` - per-extension versions + - `EXTENSION_*_VERSION` - per-extension versions, from each `.control` file's `default_version` - `EXTENSION__CURRENT_VERSION__FILES` - the current/most-recent auto-generated versioned SQL file for each extension (not all version files) -- `base.mk` includes `meta.mk` via `-include` + - Rules for generating versioned SQL files +- `base.mk` includes `control.mk` via `-include` ### The Magic of base.mk @@ -157,10 +163,11 @@ make pgxntool-sync # Update to latest pgxntool via git subtree pull ### Critical Testing Rules **NEVER use `make installcheck` directly**. Always use `make test` instead. The `make test` target ensures: -- Clean builds before testing -- Proper test isolation -- Correct test dependency installation -- Proper cleanup and result comparison +- Correct test dependency installation (`testdeps`, and `test-build` when enabled) +- Extension is installed before tests run (`install`) +- Test comparison via `installcheck`, with diffs shown on failure + +Note: `make test` intentionally does *not* depend on `clean` — depending on `clean` caused problems with incremental/watch-based builds (see `base.mk`). If your tests need a clean build to pass, that's a sign of a missing dependency elsewhere, not something to fix by adding `clean` back. **Database Connection Requirement**: PostgreSQL must be running before executing `make test`. If you get connection errors (e.g., "could not connect to server"), stop and ask the user to start PostgreSQL. @@ -204,7 +211,7 @@ When tests fail, examine the diff output carefully. The actual test output in `t ### Distribution Packaging - `make dist` creates `../PGXN-VERSION.zip` -- Always creates git tag matching version +- Creates a git tag matching version, unless that tag already exists and points at HEAD (in which case tagging is skipped) - Uses `git archive` to package - Validates repo is clean before tagging @@ -273,11 +280,12 @@ Generated files depend on: ## Scripts -- **setup.sh** - Initializes pgxntool in a new extension project (copies templates, creates directories) -- **build_meta.sh** - Strips empty fields from META.in.json to create META.json -- **meta.mk.sh** - Parses META.json via JSON.sh and generates meta.mk with Make variables -- **JSON.sh** - Third-party bash JSON parser (MIT licensed) -- **safesed** - Utility for safe sed operations +Each `*.sh` script in this directory's root (`setup.sh`, `build_meta.sh`, `meta.mk.sh`, +`control.mk.sh`, `pgxntool-sync.sh`, `update-setup-files.sh`, `pgtle.sh`, etc.) begins with +a shebang followed by a short header comment describing its purpose within the first ~10 +lines — read that header rather than relying on a hand-maintained list here. Exception: +`JSON.sh` (third-party, MIT licensed) and `safesed` are trivial utilities without such a +header. ## Related Repositories diff --git a/README.asc b/README.asc index 4159bd9..5735594 100644 --- a/README.asc +++ b/README.asc @@ -270,7 +270,7 @@ WARNING: If your project has a `.gitattributes` file, `make dist`/`make dist-onl `make forcedist` is a shortcut for `forcetag dist`: it force-recreates the tag (see `forcetag` above) before rebuilding the distribution .zip. === pgxntool-sync -This rule will pull down the latest released version of PGXNtool via `git subtree pull` and then reconcile the files `setup.sh` copied into your project (`.gitignore`, `test/deps.sql`) with a 3-way merge. +This rule will pull down the latest released version of PGXNtool via `git subtree pull` and then reconcile the files `setup.sh` copied into your project (`.gitignore`, `test/deps.sql`) with a 3-way merge (it also verifies the `test/pgxntool` symlink, recreating it if missing). NOTE: Your repository must be clean (no modified files) in order to run this. Running this command will produce a git commit of the merge. From 68e43b05d16923f5113b764db56f9871b274c962 Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Fri, 31 Jul 2026 17:38:31 -0500 Subject: [PATCH 2/4] CLAUDE.md: don't enumerate scripts by name in the Scripts section The prior fix still listed every script name in a parenthetical, which would go stale exactly the same way the list it replaced did. --- CLAUDE.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c4fa466..2a9e41a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -280,12 +280,11 @@ Generated files depend on: ## Scripts -Each `*.sh` script in this directory's root (`setup.sh`, `build_meta.sh`, `meta.mk.sh`, -`control.mk.sh`, `pgxntool-sync.sh`, `update-setup-files.sh`, `pgtle.sh`, etc.) begins with -a shebang followed by a short header comment describing its purpose within the first ~10 -lines — read that header rather than relying on a hand-maintained list here. Exception: -`JSON.sh` (third-party, MIT licensed) and `safesed` are trivial utilities without such a -header. +Each `*.sh` script in this directory's root begins with a shebang followed by a short +header comment describing its purpose within the first ~10 lines — read that header +rather than relying on a hand-maintained list here, which would just go stale the same +way this section itself once did. Exception: trivial third-party or one-line utilities +may lack such a header. ## Related Repositories From d95a1fc3b6f42c6eda6261eeb61dad7390de02a7 Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Fri, 31 Jul 2026 17:39:06 -0500 Subject: [PATCH 3/4] CLAUDE.md: don't restrict the Scripts pointer to *.sh files No reason to limit this to shell scripts specifically; a future script in any language should be covered by the same guidance. --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 2a9e41a..96077af 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -280,7 +280,7 @@ Generated files depend on: ## Scripts -Each `*.sh` script in this directory's root begins with a shebang followed by a short +Each script in this directory's root begins with a shebang followed by a short header comment describing its purpose within the first ~10 lines — read that header rather than relying on a hand-maintained list here, which would just go stale the same way this section itself once did. Exception: trivial third-party or one-line utilities From fe877ed0356840be89ea4b2dfcc16d45acc47bce Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Fri, 31 Jul 2026 17:40:41 -0500 Subject: [PATCH 4/4] CLAUDE.md: clarify which directory the Scripts section refers to "this directory's root" was ambiguous outside the context of the file itself; spell out that it means the top level of the pgxntool repo. --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 96077af..65e3bf7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -280,7 +280,7 @@ Generated files depend on: ## Scripts -Each script in this directory's root begins with a shebang followed by a short +Each script at the top level of this repository (pgxntool/) begins with a shebang followed by a short header comment describing its purpose within the first ~10 lines — read that header rather than relying on a hand-maintained list here, which would just go stale the same way this section itself once did. Exception: trivial third-party or one-line utilities