From 9e3dcbb98d90016c15cf89dfcf1e2f133cce1f43 Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Wed, 29 Jul 2026 15:01:13 -0500 Subject: [PATCH] Fix stale README/CLAUDE.md docs; rename internal-only test seam variable Found by the /release skill's API documentation review ahead of 2.2.0: - Rename `PGXNTOOL_CHECK_STALE_EXPECTED_SCRIPT` to `_CHECK_STALE_EXPECTED_SCRIPT`, establishing a leading-underscore convention for internal-only override points (test-stubbing seams, not user-facing config) that don't belong under the `PGXNTOOL_` prefix. - Document `PGTLE_VERSION` in README.asc (pgtle section + Configuration Variables) -- it was fixed and used in HISTORY.asc/CLAUDE.md but never actually documented for users. - Fix the versioned-SQL-file code example in README.asc, which still showed the truncate+append pattern that was fixed for parallel-build corruption. - Update stale `decibel/pgxntool` URLs (Install command, issue links, license links) to `Postgres-Extensions/pgxntool`, and fix `LICENCE`/ `JSON.sh.LICENCE` typos to `LICENSE`/`JSON.sh.LICENSE`. - Document `update-setup-files.sh` as directly invokable in the pgxntool-sync section. - Fix CLAUDE.md: nonexistent `install-pgtle` target -> `run-pgtle`, wrong `check-pgtle`/`run-pgtle` descriptions, wrong script name `pgtle-wrap.sh` -> `pgtle.sh`, and `make tag` creates a tag, not a branch. - Regenerate README.html from README.asc. Related changes in pgxntool-test: - Update `_CHECK_STALE_EXPECTED_SCRIPT` references in `make-test.bats`/`helpers.bash` - Document the underscore-prefix internal-only convention in the API surface definition Co-Authored-By: Claude --- CLAUDE.md | 12 ++++---- README.asc | 25 +++++++++++----- README.html | 86 ++++++++++++++++++++++++++++++++++------------------- base.mk | 11 ++----- setup.sh | 2 +- 5 files changed, 84 insertions(+), 52 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 0a83451..5db8c95 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -144,11 +144,11 @@ make # Build extension (generates versioned SQL, docs) make test # Full test: testdeps → install → installcheck → show diffs make results # Run tests and update expected output files make html # Generate HTML from Asciidoc sources -make tag # Create git branch for current META.json version +make tag # Create git tag for current META.json version make dist # Create PGXN .zip (auto-tags, places in ../) make pgtle # Generate pg_tle registration SQL (see pg_tle Support below) make check-pgtle # Check pg_tle installation and report version -make install-pgtle # Install pg_tle registration SQL files into database +make run-pgtle # Register extensions with pg_tle in the database make pgxntool-sync # Update to latest pgxntool via git subtree pull ``` @@ -204,7 +204,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 branch tag matching version +- Always creates git tag matching version - Uses `git archive` to package - Validates repo is clean before tagging @@ -227,16 +227,16 @@ pgxntool can generate pg_tle (Trusted Language Extensions) registration SQL for **Installation targets:** -- `make check-pgtle` - Checks if pg_tle is installed and reports the version. Reports version from `pg_extension` if extension has been created, or newest available version from `pg_available_extension_versions` if available but not created. Errors if pg_tle not available in cluster. Assumes `PG*` environment variables are configured. +- `make check-pgtle` - Checks if pg_tle is installed and reports the version. Reports the version from `pg_extension` if `CREATE EXTENSION pg_tle` has been run in the database. Errors if pg_tle is not available in the cluster. Assumes `PG*` environment variables are configured. -- `make install-pgtle` - Auto-detects pg_tle version and installs appropriate registration SQL files. Updates or creates pg_tle extension as needed. Determines which version range files to install based on detected version. Runs all generated SQL files via `psql` to register extensions with pg_tle. Assumes `PG*` environment variables are configured. +- `make run-pgtle` - Registers all extensions with pg_tle by executing the generated pg_tle registration SQL files. Requires pg_tle to already be installed in the target database (`CREATE EXTENSION pg_tle;`) -- it does not create the extension itself, and errors out telling you to run `make check-pgtle` if it's missing. Depends on `pgtle`, so it generates the SQL files first if needed. Assumes `PG*` environment variables are configured. **Version notation:** - `X.Y.Z+` means >= X.Y.Z - `X.Y.Z-A.B.C` means >= X.Y.Z and < A.B.C (note boundary) **Key implementation details:** -- Script: `pgxntool/pgtle-wrap.sh` (bash) +- Script: `pgxntool/pgtle.sh` (bash) - Parses `.control` files for metadata (NOT META.json) - Fixed delimiter: `$_pgtle_wrap_delimiter_$` (validated not in source) - Each output file contains ALL versions and ALL upgrade paths diff --git a/README.asc b/README.asc index 0931ec9..a799c7c 100644 --- a/README.asc +++ b/README.asc @@ -9,7 +9,7 @@ PGXNtool is meant to make developing new Postgres extensions for http://pgxn.org Currently, it consists a base Makefile that you can include instead of writing your own, a template `META.in.json` (from which `META.json` is generated — you edit the former, never the latter directly), and some test framework. More features will be added over time. -If you find any bugs or have ideas for improvements, please https://github.com/decibel/pgxntool/issues[*open an issue*]. +If you find any bugs or have ideas for improvements, please https://github.com/Postgres-Extensions/pgxntool/issues[*open an issue*]. == Install This assumes that you've already initialized your extension in git. @@ -17,7 +17,7 @@ This assumes that you've already initialized your extension in git. NOTE: The `--squash` is important! Otherwise you'll clutter your repo with a bunch of commits you probably don't want. ---- -git subtree add -P pgxntool --squash git@github.com:decibel/pgxntool.git release +git subtree add -P pgxntool --squash git@github.com:Postgres-Extensions/pgxntool.git release pgxntool/setup.sh ---- @@ -213,7 +213,7 @@ check_control: grep -q "requires = 'pgtap, test_factory'" test_factory_pgtap.control ---- -If you want to over-ride the default dependency on `pgtap` you should be able to do that with a makefile override. If you need help with that, please https://github.com/decibel/pgxntool/issues[open an issue]. +If you want to over-ride the default dependency on `pgtap` you should be able to do that with a makefile override. If you need help with that, please https://github.com/Postgres-Extensions/pgxntool/issues[open an issue]. WARNING: It will probably cause problems if you try to create a `testdeps` rule that has a recipe. Instead of doing that, put the recipe in a separate rule and make that rule a prerequisite of `testdeps` as show in the example. @@ -258,7 +258,7 @@ make PGXNTOOL_ENABLE_VERIFY_RESULTS=no results If a tag for the current version already exists and points at your current commit, `make tag` does nothing — this makes it safe for other targets (like `dist`) to depend on `tag` without worrying about re-running it. If the existing tag points at a *different* commit — meaning you likely forgot to bump the version — you'll get an error. If you're certain you want to over-write the tag, you can do `make forcetag`, which removes the existing tag (via `make rmtag`) and creates a new one. -WARNING: You will be very unhappy if you forget to update the .control file for your extension! There is an https://github.com/decibel/pgxntool/issues/1[open issue] to improve this. +WARNING: You will be very unhappy if you forget to update the .control file for your extension! There is an https://github.com/Postgres-Extensions/pgxntool/issues/1[open issue] to improve this. === dist `make dist` will create a .zip file for your current version that you can upload to PGXN. It first runs `tag` (creating/pushing the version's git tag as described above if needed), then uses `git archive` at that tag to build the .zip file, so the archive always matches the exact tagged commit. The file is named after the PGXN name and version (the top-level "name" and "version" attributes in META.json, generated from `META.in.json`). The .zip file is placed in the *parent* directory so as not to clutter up your git repo. @@ -278,6 +278,8 @@ NOTE: `git subtree pull` copies pgxntool's entire tree into your project, includ TIP: The actual work is done by `pgxntool/pgxntool-sync.sh`, so you can run it directly (`pgxntool/pgxntool-sync.sh`) if you'd rather not go through `make`. It optionally takes `` and `` arguments to pull from somewhere other than the default. +TIP: `pgxntool-sync.sh` itself delegates the 3-way merge of `setup.sh`-copied files to `pgxntool/update-setup-files.sh `, which you can also run directly -- for example, to redo or debug just the merge step without pulling again. `` is the pgxntool subtree commit that was current *before* the sync you want to re-merge. + TIP: There is also a `pgxntool-sync-%` rule if you need to do more advanced things. `make pgxntool-sync-` pulls from the ` ` defined by the `pgxntool-sync-` make variable. === pgxntool-version @@ -306,6 +308,12 @@ Generates pg_tle (Trusted Language Extensions) registration SQL files for deploy `make pgtle` generates SQL files in `pg_tle/` subdirectories organized by pg_tle version ranges. For version range details, see `pgtle_versions.md`. +Set `PGTLE_VERSION` on the command line to limit generation to the single version range that value falls into, instead of every known range: + +---- +make pgtle PGTLE_VERSION=1.5.0 +---- + === check-pgtle Checks if pg_tle is installed and reports the version. This target: - Reports the version from `pg_extension` if `CREATE EXTENSION pg_tle` has been run in the database @@ -406,8 +414,7 @@ Because it's only ever transiently present, the correct cleanup is a single `rm ---- $(EXTENSION_ext_VERSION_FILE): sql/ext.sql extension.control - @echo '/* DO NOT EDIT - AUTO-GENERATED FILE */' > $(EXTENSION_ext_VERSION_FILE) - @cat sql/ext.sql >> $(EXTENSION_ext_VERSION_FILE) + @(echo '/* DO NOT EDIT - AUTO-GENERATED FILE */'; cat sql/ext.sql) > $(EXTENSION_ext_VERSION_FILE) ---- That rule only ever targets the file matching the extension's *current* `default_version`, so editing the base `sql/{extension}.sql` and running `make` is the correct, safe way to change that one file. @@ -658,6 +665,10 @@ make dist PGXN_REMOTE=upstream Default: auto-detected, the first of `asciidoctor` or `asciidoc` found on `PATH`. Path to the Asciidoc processor used to build `.html` files from `$(ASCIIDOC_EXTS)` source files. Override if the processor you want isn't first on `PATH`, or isn't on `PATH` at all. See <<_document_handling>>. +=== PGTLE_VERSION + +Default: unset (generates every known pg_tle version range). Set on the command line to limit `make pgtle` to the single version range this value falls into. See <<_pgtle>>. + === PG_CONFIG Default: `pg_config`. Path to the `pg_config` binary used to detect the PostgreSQL version and locate PGXS. Override when the right `pg_config` isn't the one on `PATH`, such as when testing against a specific PostgreSQL install. @@ -711,4 +722,4 @@ Default: unset (PGXS is included normally). Skips including PGXS (`$(PGXS)`) ent == Copyright Copyright (c) 2026 Jim Nasby -PGXNtool is released under a https://github.com/decibel/pgxntool/blob/master/LICENCE[BSD license]. Note that it includes https://github.com/dominictarr/JSON.sh[JSON.sh], which is released under a https://github.com/decibel/pgxntool/blob/master/JSON.sh.LICENCE[MIT license]. +PGXNtool is released under a https://github.com/Postgres-Extensions/pgxntool/blob/master/LICENSE[BSD license]. Note that it includes https://github.com/dominictarr/JSON.sh[JSON.sh], which is released under a https://github.com/Postgres-Extensions/pgxntool/blob/master/JSON.sh.LICENSE[MIT license]. diff --git a/README.html b/README.html index 6e2c980..36d3cf5 100644 --- a/README.html +++ b/README.html @@ -499,16 +499,17 @@

PGXNtool

  • 9. Copyright
    • @@ -525,7 +526,7 @@

    PGXNtool

    Currently, it consists a base Makefile that you can include instead of writing your own, a template META.in.json (from which META.json is generated — you edit the former, never the latter directly), and some test framework. More features will be added over time.

    -

    If you find any bugs or have ideas for improvements, please open an issue.

    +

    If you find any bugs or have ideas for improvements, please open an issue.

    @@ -549,7 +550,7 @@

    -
    git subtree add -P pgxntool --squash git@github.com:decibel/pgxntool.git release
+
    git subtree add -P pgxntool --squash git@github.com:Postgres-Extensions/pgxntool.git release
 pgxntool/setup.sh
    @@ -918,7 +919,7 @@

    -

    If you want to over-ride the default dependency on pgtap you should be able to do that with a makefile override. If you need help with that, please open an issue.

    +

    If you want to over-ride the default dependency on pgtap you should be able to do that with a makefile override. If you need help with that, please open an issue.

    @@ -1027,7 +1028,7 @@

    4.
    Warning

    -You will be very unhappy if you forget to update the .control file for your extension! There is an open issue to improve this. +You will be very unhappy if you forget to update the .control file for your extension! There is an open issue to improve this.
    @@ -1114,6 +1115,18 @@

    Tip

    +pgxntool-sync.sh itself delegates the 3-way merge of setup.sh-copied files to pgxntool/update-setup-files.sh <old-pgxntool-commit>, which you can also run directly — for example, to redo or debug just the merge step without pulling again. <old-pgxntool-commit> is the pgxntool subtree commit that was current before the sync you want to re-merge. + + + + +
    + + + + @@ -1184,6 +1197,14 @@

    make pgtle generates SQL files in pg_tle/ subdirectories organized by pg_tle version ranges. For version range details, see pgtle_versions.md.

    +
    +

    Set PGTLE_VERSION on the command line to limit generation to the single version range that value falls into, instead of every known range:

    +
    +
    +
    +
    make pgtle PGTLE_VERSION=1.5.0
    +
    +

    4.15. check-pgtle

    @@ -1363,8 +1384,7 @@ 

    $(EXTENSION_ext_VERSION_FILE): sql/ext.sql extension.control
-	@echo '/* DO NOT EDIT - AUTO-GENERATED FILE */' > $(EXTENSION_ext_VERSION_FILE)
-	@cat sql/ext.sql >> $(EXTENSION_ext_VERSION_FILE)
    + @(echo '/* DO NOT EDIT - AUTO-GENERATED FILE */'; cat sql/ext.sql) > $(EXTENSION_ext_VERSION_FILE)

    @@ -1838,61 +1858,67 @@

    -

    8.3. PG_CONFIG

    +

    8.3. PGTLE_VERSION

    +
    +

    Default: unset (generates every known pg_tle version range). Set on the command line to limit make pgtle to the single version range this value falls into. See pgtle.

    +
    +
    +
    +

    8.4. PG_CONFIG

    Default: pg_config. Path to the pg_config binary used to detect the PostgreSQL version and locate PGXS. Override when the right pg_config isn’t the one on PATH, such as when testing against a specific PostgreSQL install.

    -

    8.4. TESTDIR

    +

    8.5. TESTDIR

    Default: test. Root directory for test input files: $(TESTDIR)/sql/, $(TESTDIR)/expected/, $(TESTDIR)/build/, $(TESTDIR)/install/. Overriding this on its own is unusual; it mainly exists so TESTOUT has a sensible default.

    -

    8.5. TESTOUT

    +

    8.6. TESTOUT

    Default: $(TESTDIR). Directory pg_regress writes actual test output to — $(TESTOUT)/results/, $(TESTOUT)/regression.diffs, etc. — via --outputdir in REGRESS_OPTS. Kept separate from TESTDIR so generated output can be pointed somewhere other than the directory holding your checked-in sql/expected files, if you want that separation.

    -

    8.6. PGXNTOOL_VERIFY_RESULTS_MODE

    +

    8.7. PGXNTOOL_VERIFY_RESULTS_MODE

    Default: pgtap. Controls how the verify-results safeguard decides whether tests are failing.

    -

    8.6.1. pgtap

    +

    8.7.1. pgtap

    Scans test/results/*.out for pgTap not ok lines and plan mismatches, falling back to checking for regression.diffs too. Use this mode when your test suite uses pgTap.

    -

    8.6.2. diffs

    +

    8.7.2. diffs

    Checks only for regression.diffs, matching classic pg_regress behavior. Use this mode when your tests use plain SQL expected-output comparison only.

    -

    8.7. PGXNTOOL_ENABLE_TEST_BUILD *

    +

    8.8. PGXNTOOL_ENABLE_TEST_BUILD *

    Default: auto-detected — yes if test/build/*.sql files exist, no otherwise. Enables or disables the test-build pre-flight SQL check. Set explicitly to yes if you want an error when test/build/ unexpectedly has no SQL files (catches accidental deletion of its contents), or to no to disable the check even when files are present.

    -

    8.8. PGXNTOOL_ENABLE_TEST_INSTALL *

    +

    8.9. PGXNTOOL_ENABLE_TEST_INSTALL *

    Default: auto-detected — yes if test/install/*.sql files exist, no otherwise. Enables or disables the test/install schedule-based setup feature. Same explicit-override semantics as PGXNTOOL_ENABLE_TEST_BUILD.

    -

    8.9. PGXNTOOL_ENABLE_VERIFY_RESULTS *

    +

    8.10. PGXNTOOL_ENABLE_VERIFY_RESULTS *

    Default: yes. Enables or disables the verify-results safeguard that blocks make results when tests are failing. Setting it to empty on the command line (make PGXNTOOL_ENABLE_VERIFY_RESULTS= results) also disables it.

    -

    8.10. PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED *

    +

    8.11. PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED *

    Default: yes. Enables or disables the check-stale-expected safeguard, which fails make test if test/expected/ (or test/build/expected/) contains a .out file with no corresponding .sql file — catching a stale file left behind after a test was renamed or removed. Set to no to make the check a complete no-op (it’s dropped from TEST_DEPS entirely).

    @@ -1901,13 +1927,13 @@

    -

    8.11. PGXNTOOL_CHECK_EXPECTED_FILE_TYPES *

    +

    8.12. PGXNTOOL_CHECK_EXPECTED_FILE_TYPES *

    Default: yes. Sub-check of check-stale-expected, independent of PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED: fails (with a distinct error message and exit code from the orphaned-.out check) if test/expected/ (or test/build/expected/) contains any file that isn’t *.out. Set to no to disable just this sub-check while leaving the orphaned-.out check active.

    -

    8.12. PGXNTOOL_NO_PGXS_INCLUDE

    +

    8.13. PGXNTOOL_NO_PGXS_INCLUDE

    Default: unset (PGXS is included normally). Skips including PGXS ($(PGXS)) entirely. This is only for advanced scenarios where you need to manage the PGXS include yourself; most projects should never set this.

    @@ -1921,14 +1947,14 @@

    Copyright (c) 2026 Jim Nasby <Jim.Nasby@gmail.com>

    -

    PGXNtool is released under a BSD license. Note that it includes JSON.sh, which is released under a MIT license.

    +

    PGXNtool is released under a BSD license. Note that it includes JSON.sh, which is released under a MIT license.

    diff --git a/base.mk b/base.mk index 0f9d9c3..e77cff2 100644 --- a/base.mk +++ b/base.mk @@ -211,14 +211,9 @@ PGXNTOOL_VERIFY_RESULTS_MODE ?= pgtap # - Passed through to check-stale-expected.sh; see that script for the # distinct error message/exit code this sub-check uses # -# Variable: PGXNTOOL_CHECK_STALE_EXPECTED_SCRIPT +# Variable: _CHECK_STALE_EXPECTED_SCRIPT (internal shim, not user-facing) # - Path to the script the check-stale-expected target invokes # - Default: $(PGXNTOOL_DIR)/test/bin/check-stale-expected.sh -# - Exists so a test can swap in a stub script (e.g. one that just records -# that it was called) without needing to fake out any other part of -# PGXNTOOL_DIR, which many unrelated targets also read. See -# pgxntool-test's CLAUDE.md, "Proving a Script Was/Wasn't Invoked" -# (under "Testing"), for the pattern this supports. # # Implementation: See check-stale-expected target definition (search for # "check-stale-expected:" in this file) @@ -235,7 +230,7 @@ else PGXNTOOL_CHECK_EXPECTED_FILE_TYPES = yes endif -PGXNTOOL_CHECK_STALE_EXPECTED_SCRIPT ?= $(PGXNTOOL_DIR)/test/bin/check-stale-expected.sh +_CHECK_STALE_EXPECTED_SCRIPT ?= $(PGXNTOOL_DIR)/test/bin/check-stale-expected.sh # Generate unique database name for tests to prevent conflicts across projects # Uses project name + first 5 chars of md5 hash of current directory @@ -344,7 +339,7 @@ TEST_DEPS = testdeps ifeq ($(PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED),yes) .PHONY: check-stale-expected check-stale-expected: installcheck - @$(PGXNTOOL_CHECK_STALE_EXPECTED_SCRIPT) $(TESTDIR) $(PGXNTOOL_CHECK_EXPECTED_FILE_TYPES) + @$(_CHECK_STALE_EXPECTED_SCRIPT) $(TESTDIR) $(PGXNTOOL_CHECK_EXPECTED_FILE_TYPES) TEST_DEPS += check-stale-expected endif diff --git a/setup.sh b/setup.sh index 54b3633..8a31d0e 100755 --- a/setup.sh +++ b/setup.sh @@ -87,4 +87,4 @@ rmdir src If everything looks good then -git commit -am 'Add pgxntool (https://github.com/decibel/pgxntool/tree/release)'" +git commit -am 'Add pgxntool (https://github.com/Postgres-Extensions/pgxntool/tree/release)'"

    +
    Tip
    +    		 There is also a pgxntool-sync-% rule if you need to do more advanced things. make pgxntool-sync-<name> pulls from the <repo> <ref> defined by the pgxntool-sync-<name> make variable.