From bb59263c80915c38208cb9b0923a69aeb3c9e934 Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Mon, 3 Aug 2026 17:28:28 -0500 Subject: [PATCH 1/2] ci.yml: reformat the Test strategy comment, document pg-tle-test/pg-tle-upgrade-test The "Test strategy" summary listed job names in a manually space-padded "name -- description" column, which read like a Makefile target list or a formatted spec table rather than a plain comment. Restructured each entry as a small heading (the job name alone, minimally indented) with its description as ordinary wrapped prose underneath. Also documented pg-tle-test and pg-tle-upgrade-test, which this summary never mentioned even though both jobs already exist (added in PR #47) -- and trimmed wordiness in the `test` job's own step comment. Comment-only: no job, matrix, or CI-behavior change. --- .github/workflows/ci.yml | 72 ++++++++++++++++++++++++++-------------- 1 file changed, 48 insertions(+), 24 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5fb8a02..b964b12 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -243,23 +243,46 @@ jobs: # Test strategy # # A cat_tools install can be arrived at several ways, each of which can break - # differently, so each is exercised by its own job below (the per-job comments - # carry the details; this is the big picture): + # differently, so each is exercised by its own job below (the per-job + # comments carry the details; this is the big picture): # - # test -- FRESH install: CREATE EXTENSION at the current - # version on every supported PostgreSQL. The baseline - # a brand-new user gets. - # extension-update-test -- IN-PLACE update: CREATE EXTENSION at an OLD version - # then ALTER EXTENSION UPDATE (same PostgreSQL, no - # pg_upgrade). - # pg-upgrade-test -- BINARY pg_upgrade, SINGLE jump: install an OLD - # version on an OLD major, binary-upgrade the cluster - # straight to a NEWER major (skipping intermediate - # majors), then update the extension. Proves objects - # created on an old server work when read on a new one. - # pg-upgrade-stepwise -- BINARY pg_upgrade, EVERY major in sequence: one - # cluster climbing 10 -> 11 -> ... -> 18, exercising - # each individual major-to-major transition in turn. + # test + # FRESH install: CREATE EXTENSION at the current version, on every + # supported PostgreSQL major. The baseline a brand-new user gets. + # + # pg-upgrade-test + # BINARY pg_upgrade, SINGLE jump: install an OLD version on an OLD major, + # binary-upgrade the cluster straight to a NEWER major (skipping + # intermediate majors), then update the extension. Proves objects created + # on an old server work when read on a new one. + # + # pg-upgrade-stepwise + # BINARY pg_upgrade, EVERY major in sequence: one cluster climbing + # 10 -> 11 -> ... -> 18, exercising each individual major-to-major + # transition in turn. + # + # extension-update-test + # IN-PLACE update: CREATE EXTENSION at an OLD version then ALTER EXTENSION + # UPDATE (same PostgreSQL, no pg_upgrade). + # + # pg-tle-test + # The SAME majors as `test`, proving cat_tools actually works when + # deployed via pg_tle (AWS's Trusted Language Extensions) instead of a + # filesystem .control file -- the same fresh-install and update-path + # scenarios `test`/extension-update-test prove for a filesystem install, + # run again through pg_tle's own registration. That proof only means what + # it claims if pg_tle ISOLATION holds throughout the run (a stale + # filesystem .control file silently wins over a pg_tle registration of + # the same name -- PostgreSQL just resolves from disk instead of + # erroring), so every step here is bracketed by filesystem-cleanliness + # checks -- isolation is the precondition for a trustworthy result, not + # the point of the job. NOT folded into `test`: pg_tle needs + # shared_preload_libraries (mixing pg_tle/non-pg_tle installs on one + # cluster can misbehave), so it needs its own dedicated cluster. + # + # pg-tle-upgrade-test + # The pg_tle-deployed equivalent of pg-upgrade-test, on the jump pairs + # within pg_tle's own supported PostgreSQL range. # # Supported update origins are 0.2.0, 0.2.1 and 0.2.2 (0.1.x is unsupported). # 0.2.0 and 0.2.1 are BOTH tested as origins because ALTER EXTENSION UPDATE @@ -306,16 +329,17 @@ jobs: - name: Test on PostgreSQL ${{ matrix.pg }} run: | # Fail if the relkind drift source is empty (headers missing): the - # drift check must actually run on every version, not pass silently. + # drift check must run on every version, not pass silently. make check-relkind-source # verify-results is the real gate: base.mk declares `verify-results: - # $(TEST_DEPS)`, not `verify-results: test` -- deliberately, since test's own - # recipe now exits non-zero as soon as it sees a regression, which would abort - # the chain before verify-results got to inspect and report the diff. Either - # way this runs the suite (via installcheck, one of $(TEST_DEPS)) and then - # checks the pgtap/regression.diffs. A bare `make test` is redundant here: - # it now also exits non-zero on regressions (pgxntool 2.3.0+), but - # verify-results is still the stricter, documented check. + # $(TEST_DEPS)`, not `verify-results: test`, because test's own + # recipe now exits non-zero on a regression, which would abort the + # chain before verify-results could inspect and report the diff. + # Either way this runs the suite via installcheck, then checks + # pgtap/regression.diffs. A bare `make test` is redundant here for + # the same reason -- it now also exits non-zero on a regression + # (pgxntool 2.3.0+), but verify-results is the stricter, documented + # check. make verify-results # Style linter (https://github.com/Postgres-Extensions/linter, vendored at From 33412ede5bd63c5337925f58ae59e3e556121f06 Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Mon, 3 Aug 2026 17:44:47 -0500 Subject: [PATCH 2/2] CI: Test strategy comment: don't format job names as bare declarations Each entry's job name sat alone on its own line, unindented -- reads like a Makefile target declaration rather than a reference to a CI job name, and this repo's own Makefile has real hyphenated targets (test-long, test-update, ...) a reader could easily conflate these with. Only one of these names (test) even has a corresponding make target; formatting the rest identically was actively misleading. Reworded each into an ordinary prose sentence ("The `test` job runs...") so the name reads as a backticked reference inside a sentence, not a declaration. --- .github/workflows/ci.yml | 61 +++++++++++++++++++--------------------- 1 file changed, 29 insertions(+), 32 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b964b12..c54de16 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -246,43 +246,40 @@ jobs: # differently, so each is exercised by its own job below (the per-job # comments carry the details; this is the big picture): # - # test - # FRESH install: CREATE EXTENSION at the current version, on every - # supported PostgreSQL major. The baseline a brand-new user gets. + # The `test` job runs a FRESH install: CREATE EXTENSION at the current + # version, on every supported PostgreSQL major. The baseline a brand-new + # user gets. # - # pg-upgrade-test - # BINARY pg_upgrade, SINGLE jump: install an OLD version on an OLD major, - # binary-upgrade the cluster straight to a NEWER major (skipping - # intermediate majors), then update the extension. Proves objects created - # on an old server work when read on a new one. + # The `pg-upgrade-test` job does a BINARY pg_upgrade, SINGLE jump: install + # an OLD version on an OLD major, binary-upgrade the cluster straight to a + # NEWER major (skipping intermediate majors), then update the extension. + # Proves objects created on an old server work when read on a new one. # - # pg-upgrade-stepwise - # BINARY pg_upgrade, EVERY major in sequence: one cluster climbing - # 10 -> 11 -> ... -> 18, exercising each individual major-to-major - # transition in turn. + # The `pg-upgrade-stepwise` job does a BINARY pg_upgrade, EVERY major in + # sequence: one cluster climbing 10 -> 11 -> ... -> 18, exercising each + # individual major-to-major transition in turn. # - # extension-update-test - # IN-PLACE update: CREATE EXTENSION at an OLD version then ALTER EXTENSION - # UPDATE (same PostgreSQL, no pg_upgrade). + # The `extension-update-test` job proves an IN-PLACE update: CREATE + # EXTENSION at an OLD version then ALTER EXTENSION UPDATE (same + # PostgreSQL, no pg_upgrade). # - # pg-tle-test - # The SAME majors as `test`, proving cat_tools actually works when - # deployed via pg_tle (AWS's Trusted Language Extensions) instead of a - # filesystem .control file -- the same fresh-install and update-path - # scenarios `test`/extension-update-test prove for a filesystem install, - # run again through pg_tle's own registration. That proof only means what - # it claims if pg_tle ISOLATION holds throughout the run (a stale - # filesystem .control file silently wins over a pg_tle registration of - # the same name -- PostgreSQL just resolves from disk instead of - # erroring), so every step here is bracketed by filesystem-cleanliness - # checks -- isolation is the precondition for a trustworthy result, not - # the point of the job. NOT folded into `test`: pg_tle needs - # shared_preload_libraries (mixing pg_tle/non-pg_tle installs on one - # cluster can misbehave), so it needs its own dedicated cluster. + # The `pg-tle-test` job covers the SAME majors as `test`, proving cat_tools + # actually works when deployed via pg_tle (AWS's Trusted Language + # Extensions) instead of a filesystem .control file -- the same + # fresh-install and update-path scenarios `test`/extension-update-test + # prove for a filesystem install, run again through pg_tle's own + # registration. That proof only means what it claims if pg_tle ISOLATION + # holds throughout the run (a stale filesystem .control file silently wins + # over a pg_tle registration of the same name -- PostgreSQL just resolves + # from disk instead of erroring), so every step here is bracketed by + # filesystem-cleanliness checks -- isolation is the precondition for a + # trustworthy result, not the point of the job. NOT folded into `test`: + # pg_tle needs shared_preload_libraries (mixing pg_tle/non-pg_tle installs + # on one cluster can misbehave), so it needs its own dedicated cluster. # - # pg-tle-upgrade-test - # The pg_tle-deployed equivalent of pg-upgrade-test, on the jump pairs - # within pg_tle's own supported PostgreSQL range. + # The `pg-tle-upgrade-test` job is the pg_tle-deployed equivalent of + # `pg-upgrade-test`, on the jump pairs within pg_tle's own supported + # PostgreSQL range. # # Supported update origins are 0.2.0, 0.2.1 and 0.2.2 (0.1.x is unsupported). # 0.2.0 and 0.2.1 are BOTH tested as origins because ALTER EXTENSION UPDATE