From d61a658a24902124d6a7c831c6e3190c43b53560 Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Thu, 16 Jul 2026 14:41:42 -0500 Subject: [PATCH 1/4] 1.0.0: Promote to stable, add changelog and release process doc - release_status: testing -> stable in META.in.json/META.json - Fix stale resources URLs (decibel/extension_drop -> Postgres-Extensions/extension_tools) - Add HISTORY.asc summarizing changes since 0.1.1 - Add RELEASE.md documenting how to cut and publish a release --- HISTORY.asc | 37 ++++++++++++++++++++++ META.in.json | 10 +++--- META.json | 10 +++--- RELEASE.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 134 insertions(+), 10 deletions(-) create mode 100644 HISTORY.asc create mode 100644 RELEASE.md diff --git a/HISTORY.asc b/HISTORY.asc new file mode 100644 index 0000000..a445f4f --- /dev/null +++ b/HISTORY.asc @@ -0,0 +1,37 @@ +1.0.0 +----- +== PostgreSQL 9.3-17 compatibility +Fixed the test suite and install script to work across the full range of +supported PostgreSQL versions: `CREATE EXTENSION ... CASCADE` isn't +available before PG10, so `test/deps.sql` falls back to an explicit +`CREATE EXTENSION cat_tools` first; the test Makefile now sets +`PGXNTOOL_NO_PGXS_INCLUDE` for pre-9.5; and test assertions were updated +for stricter type casting in newer PostgreSQL versions. + +== Remove redundant client_min_messages handling from install script +`CREATE EXTENSION` already raises `client_min_messages` to `WARNING` for +the install script (only-raising, so a stricter caller is respected) and +restores it afterward, so the script's own save/restore was redundant -- +and being blind to the caller's level, it could actually lower a +stricter caller's `client_min_messages` during install. + +== Switch CI from Travis to GitHub Actions +Also added Claude Code review workflows. + +== Update pgxntool to 2.1.0 +Picks up numerous bug fixes accumulated since the last release: git +worktree support, a control-file parsing bug, bash 3.2 compatibility, a +`pgxntool-sync` remote URL fix, and pruning of pgxntool's own dev-only +files after each sync. See `pgxntool/HISTORY.asc` for the full list. + +== Mark release as stable +No functional issues turned up in the 9+ years since 0.1.1; promoting +from `testing` to `stable`. + +0.1.1 +----- +Fix extension dependencies. + +0.1.0 +----- +Initial release. diff --git a/META.in.json b/META.in.json index c118711..31284f2 100644 --- a/META.in.json +++ b/META.in.json @@ -28,7 +28,7 @@ "maintainer": [ "Jim Nasby " ], "X_comment": "Optional. Status of distribution. Allowed values: unstable, testing, stable", - "release_status": "testing", + "release_status": "stable", "X_comment": "REQUIRED. License(s) distribution is released under. http://pgxn.org/spec/#license", "license": "postgresql", @@ -58,13 +58,13 @@ "X_comment": "Optional. \"resources\": Web resources available for this distribution. http://pgxn.org/spec/#resources", "resources": { - "homepage": "http://github.com/decibel/extension_drop/", + "homepage": "https://github.com/Postgres-Extensions/extension_tools/", "bugtracker": { - "web": "http://github.com/decibel/extension_drop/issues" + "web": "https://github.com/Postgres-Extensions/extension_tools/issues" }, "repository": { - "url": "git://github.com/decibel/extension_drop.git", - "web": "http://github.com/decibel/extension_drop/", + "url": "https://github.com/Postgres-Extensions/extension_tools.git", + "web": "https://github.com/Postgres-Extensions/extension_tools/", "type": "git" } }, diff --git a/META.json b/META.json index 42ba119..d02cded 100644 --- a/META.json +++ b/META.json @@ -28,7 +28,7 @@ "maintainer": [ "Jim Nasby " ], "X_comment": "Optional. Status of distribution. Allowed values: unstable, testing, stable", - "release_status": "testing", + "release_status": "stable", "X_comment": "REQUIRED. License(s) distribution is released under. http://pgxn.org/spec/#license", "license": "postgresql", @@ -57,13 +57,13 @@ "X_comment": "Optional. \"resources\": Web resources available for this distribution. http://pgxn.org/spec/#resources", "resources": { - "homepage": "http://github.com/decibel/extension_drop/", + "homepage": "https://github.com/Postgres-Extensions/extension_tools/", "bugtracker": { - "web": "http://github.com/decibel/extension_drop/issues" + "web": "https://github.com/Postgres-Extensions/extension_tools/issues" }, "repository": { - "url": "git://github.com/decibel/extension_drop.git", - "web": "http://github.com/decibel/extension_drop/", + "url": "https://github.com/Postgres-Extensions/extension_tools.git", + "web": "https://github.com/Postgres-Extensions/extension_tools/", "type": "git" } }, diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 0000000..2bf238a --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,87 @@ +# Release Process + +How to cut a release of this distribution (`extension_drop`, name from +`META.json`'s top-level `name` field) and publish it to PGXN. Written to be +followed standalone, without other context. + +## Overview + +Releases use pgxntool's built-in `make tag`/`make dist` mechanics to produce a +`.zip`. There is currently **no CI automation for publishing** — the zip must +be uploaded to PGXN Manager by hand. See "Future: CI automation" below for the +planned upgrade path. + +## Steps + +1. Make sure `master` is in the state you want released, and CI is green. + +2. Bump the version: + - Edit `META.in.json`: bump the top-level `version` field AND the matching + `version` under `provides..version`. Do **not** touch + `meta-spec.version` — that's the PGXN metadata spec version, always + `1.0.0` regardless of your distribution's version. + - Edit `.control`: bump `default_version` to match. + - If maturity is changing, also update `release_status` in `META.in.json` + (`unstable` -> `testing` -> `stable`). + - Regenerate `META.json`: `rm -f META.json && make META.json`. It's a + derived file — never hand-edit it directly (see `META.in.json` vs + `META.json` in `pgxntool/CLAUDE.md`). + +3. Add a changelog entry in `HISTORY.asc` at the repo root (this project's + own file — not `pgxntool/HISTORY.asc`, which documents pgxntool itself). + Format: a line with the version number, a line of dashes matching its + length, then one or more `== ` blocks with a short prose blurb + each. Newest version goes at the top. Follow the existing entries in this + file for the exact style. + +4. Commit the version bump + changelog together in one commit. Message + convention used by this project: `": "` (e.g. + `"1.0.0: Add PostgreSQL 9.3-17 support, promote to stable"`). + +5. Make sure your `origin` git remote points at the canonical upstream repo + (`Postgres-Extensions/extension_tools`, not a personal fork) — + `make tag` pushes to whatever `origin` is, and a tag pushed to a fork does + nothing for PGXN. + +6. Run `make dist`. This: + - Refuses to run with uncommitted changes. + - Creates (or verifies) a git tag matching `PGXNVERSION` — the bare version + number, e.g. `1.0.0`, no `v` prefix, matching this project's convention + (check `meta.mk` if unsure what `PGXNVERSION` resolved to) — and pushes + it to `origin`. + - Runs `git archive` at that tag into `../-.zip` (e.g. + `../extension_drop-1.0.0.zip`). + - If you need to redo a release before anyone's downloaded it: + `make forcedist` (deletes + recreates the tag, rebuilds the zip). Don't + do this once the version has been public for a while — moving a + published tag out from under people is disruptive. + +7. Upload the zip at https://manager.pgxn.org/ (log in, use the release form). + You need a registered PGXN Manager account with rights to this + distribution. + +8. Verify the new version shows up at `https://pgxn.org/dist//` (can + take a few minutes to index). + +## Future: CI automation + +Right now this is entirely manual. The `pgtap` extension (a sibling project, +not part of this org) has a `.github/workflows/release.yml` that +auto-publishes to PGXN on tag push, using the `pgxn/pgxn-tools` Docker image +(`pgxn-bundle` + `pgxn-release` steps), and auto-creates a GitHub release from +the changelog. Adopting the same pattern here would remove steps 6-7 above, +but requires storing PGXN Manager credentials as a GitHub Actions secret — +deliberately deferred for this release. + +## Notes / gotchas discovered while writing this + +- pgxntool's own `make tag`/`make dist` create a *real* git tag, despite + `pgxntool/README.asc` describing the result as a "branch" — that's stale + wording in the docs, not current behavior. +- There's no automated check that `META.in.json`'s top-level version, its + `provides..version`, and `.control`'s + `default_version` all agree — verify all three by hand before tagging. +- `META.in.json`'s `resources` block (homepage/bugtracker/repository URLs) + should point at the actual current repo home. It had drifted to a stale + `decibel/extension_drop` URL (GitHub redirects it via repo-transfer, but + that shouldn't be relied on) until fixed as part of the 1.0.0 release prep. From 16e042d79bb8afd4da9d24728c1f5f57b9b04073 Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Thu, 16 Jul 2026 15:27:48 -0500 Subject: [PATCH 2/4] Address review feedback on release-prep PR - HISTORY.asc: trim to only user-facing changes (the PG-version test-suite fixes and CI/pgxntool changes are dev-only or predate the 0.1.1 release itself, once the actual commit dates are checked against the 2017-07-12 PGXN upload date) - RELEASE.md: document an ongoing HISTORY.asc/upgrade-script convention (STABLE section + ----stable.sql, renamed at release time), drop the release_status bump (rarely changes), stop force-deleting META.json, note make test as a final pre-tag check, and point at the pgxntool 'make dist' labeled issues to review before releasing --- HISTORY.asc | 17 ----------- RELEASE.md | 85 +++++++++++++++++++++++++++++++++-------------------- 2 files changed, 53 insertions(+), 49 deletions(-) diff --git a/HISTORY.asc b/HISTORY.asc index a445f4f..f483708 100644 --- a/HISTORY.asc +++ b/HISTORY.asc @@ -1,13 +1,5 @@ 1.0.0 ----- -== PostgreSQL 9.3-17 compatibility -Fixed the test suite and install script to work across the full range of -supported PostgreSQL versions: `CREATE EXTENSION ... CASCADE` isn't -available before PG10, so `test/deps.sql` falls back to an explicit -`CREATE EXTENSION cat_tools` first; the test Makefile now sets -`PGXNTOOL_NO_PGXS_INCLUDE` for pre-9.5; and test assertions were updated -for stricter type casting in newer PostgreSQL versions. - == Remove redundant client_min_messages handling from install script `CREATE EXTENSION` already raises `client_min_messages` to `WARNING` for the install script (only-raising, so a stricter caller is respected) and @@ -15,15 +7,6 @@ restores it afterward, so the script's own save/restore was redundant -- and being blind to the caller's level, it could actually lower a stricter caller's `client_min_messages` during install. -== Switch CI from Travis to GitHub Actions -Also added Claude Code review workflows. - -== Update pgxntool to 2.1.0 -Picks up numerous bug fixes accumulated since the last release: git -worktree support, a control-file parsing bug, bash 3.2 compatibility, a -`pgxntool-sync` remote URL fix, and pruning of pgxntool's own dev-only -files after each sync. See `pgxntool/HISTORY.asc` for the full list. - == Mark release as stable No functional issues turned up in the 9+ years since 0.1.1; promoting from `testing` to `stable`. diff --git a/RELEASE.md b/RELEASE.md index 2bf238a..cbbdaf6 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -11,39 +11,60 @@ Releases use pgxntool's built-in `make tag`/`make dist` mechanics to produce a be uploaded to PGXN Manager by hand. See "Future: CI automation" below for the planned upgrade path. -## Steps +## Ongoing development (every PR, between releases) + +Keep the next release ready to cut at any time: + +- If a PR makes a user-facing change (bug fix, behavior change, new/changed + function, etc. — CI config, docs-for-contributors, and other internal-only + changes don't count), add an entry to `HISTORY.asc` at the repo root: + - If the file's top section is already headed `STABLE`, add your + `== ` block to it. + - If the top section is a real version number (nothing has changed since + the last release yet), insert a new section above it headed `STABLE` + (dashes: `------`, 6 characters) with your entry. +- If a PR changes an extension's SQL (`sql/.sql`), also maintain the + upgrade script from the last released version to `stable`: + `sql/----stable.sql`. Create it if it doesn't + exist yet (first SQL-touching PR since the last release). Every subsequent + PR that changes that extension's SQL adds whatever `ALTER ...`/ + `CREATE OR REPLACE ...` statements are needed to bring an existing install + on the last released version up to your changes. + +This way, a release is just renaming things — see step 2 below — not writing +a changelog or an upgrade path from scratch under time pressure. + +## Cutting a release 1. Make sure `master` is in the state you want released, and CI is green. -2. Bump the version: +2. Rename the accumulated `STABLE` markers to the real version number: - Edit `META.in.json`: bump the top-level `version` field AND the matching `version` under `provides..version`. Do **not** touch `meta-spec.version` — that's the PGXN metadata spec version, always `1.0.0` regardless of your distribution's version. - Edit `.control`: bump `default_version` to match. - - If maturity is changing, also update `release_status` in `META.in.json` - (`unstable` -> `testing` -> `stable`). - - Regenerate `META.json`: `rm -f META.json && make META.json`. It's a - derived file — never hand-edit it directly (see `META.in.json` vs - `META.json` in `pgxntool/CLAUDE.md`). - -3. Add a changelog entry in `HISTORY.asc` at the repo root (this project's - own file — not `pgxntool/HISTORY.asc`, which documents pgxntool itself). - Format: a line with the version number, a line of dashes matching its - length, then one or more `== ` blocks with a short prose blurb - each. Newest version goes at the top. Follow the existing entries in this - file for the exact style. - -4. Commit the version bump + changelog together in one commit. Message - convention used by this project: `": "` (e.g. - `"1.0.0: Add PostgreSQL 9.3-17 support, promote to stable"`). - -5. Make sure your `origin` git remote points at the canonical upstream repo + - In `HISTORY.asc`, rename the top `STABLE` heading to the new version + number, and its dashes line to match the new heading's length. + - `git mv sql/----stable.sql` to + `sql/----.sql`. + - Run `make META.json` (no need to `rm` it first — make only rebuilds it + when `META.in.json` is newer). It's a derived file — never hand-edit it + directly (see `META.in.json` vs `META.json` in `pgxntool/CLAUDE.md`). + - Run `make test` as a final check before committing — this also + exercises the `META.json` regeneration as part of the normal build. + +3. Commit the version bump + changelog + renamed upgrade script together in + one commit. Message convention used by this project: + `": "` (e.g. `"1.0.0: Add PostgreSQL 9.3-17 + support, promote to stable"`). + +4. Make sure your `origin` git remote points at the canonical upstream repo (`Postgres-Extensions/extension_tools`, not a personal fork) — `make tag` pushes to whatever `origin` is, and a tag pushed to a fork does nothing for PGXN. -6. Run `make dist`. This: +5. Run `make dist`. This: - Refuses to run with uncommitted changes. - Creates (or verifies) a git tag matching `PGXNVERSION` — the bare version number, e.g. `1.0.0`, no `v` prefix, matching this project's convention @@ -56,11 +77,18 @@ planned upgrade path. do this once the version has been public for a while — moving a published tag out from under people is disruptive. -7. Upload the zip at https://manager.pgxn.org/ (log in, use the release form). + Before running this, check `Postgres-Extensions/pgxntool`'s open issues + labeled `make dist` — several `make dist` gaps found while writing this + doc were filed there instead of fixed by hand each release (version + consistency, `META.json` freshness, URL reachability, and more may + accumulate over time). Review whether any open issue there affects this + release before proceeding. + +6. Upload the zip at https://manager.pgxn.org/ (log in, use the release form). You need a registered PGXN Manager account with rights to this distribution. -8. Verify the new version shows up at `https://pgxn.org/dist//` (can +7. Verify the new version shows up at `https://pgxn.org/dist//` (can take a few minutes to index). ## Future: CI automation @@ -69,7 +97,7 @@ Right now this is entirely manual. The `pgtap` extension (a sibling project, not part of this org) has a `.github/workflows/release.yml` that auto-publishes to PGXN on tag push, using the `pgxn/pgxn-tools` Docker image (`pgxn-bundle` + `pgxn-release` steps), and auto-creates a GitHub release from -the changelog. Adopting the same pattern here would remove steps 6-7 above, +the changelog. Adopting the same pattern here would remove steps 5-6 above, but requires storing PGXN Manager credentials as a GitHub Actions secret — deliberately deferred for this release. @@ -77,11 +105,4 @@ deliberately deferred for this release. - pgxntool's own `make tag`/`make dist` create a *real* git tag, despite `pgxntool/README.asc` describing the result as a "branch" — that's stale - wording in the docs, not current behavior. -- There's no automated check that `META.in.json`'s top-level version, its - `provides..version`, and `.control`'s - `default_version` all agree — verify all three by hand before tagging. -- `META.in.json`'s `resources` block (homepage/bugtracker/repository URLs) - should point at the actual current repo home. It had drifted to a stale - `decibel/extension_drop` URL (GitHub redirects it via repo-transfer, but - that shouldn't be relied on) until fixed as part of the 1.0.0 release prep. + wording in the docs, not current behavior (filed upstream to get fixed). From 14c30aa7ca602f683cf99bdd105e668edf6d8232 Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Thu, 16 Jul 2026 15:28:56 -0500 Subject: [PATCH 3/4] RELEASE.md: fix inaccurate example, caveat CI-green until installcheck actually fails --- RELEASE.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index cbbdaf6..07da220 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -37,6 +37,10 @@ a changelog or an upgrade path from scratch under time pressure. ## Cutting a release 1. Make sure `master` is in the state you want released, and CI is green. + **Caveat:** as of this writing, CI passing doesn't actually mean the test + suite passed — see "CI doesn't fail on test failures" below. Until that's + fixed, also eyeball the actual `pg_regress` output in the CI logs (or run + `make test` locally), not just the green checkmark. 2. Rename the accumulated `STABLE` markers to the real version number: - Edit `META.in.json`: bump the top-level `version` field AND the matching @@ -56,8 +60,7 @@ a changelog or an upgrade path from scratch under time pressure. 3. Commit the version bump + changelog + renamed upgrade script together in one commit. Message convention used by this project: - `": "` (e.g. `"1.0.0: Add PostgreSQL 9.3-17 - support, promote to stable"`). + `": "` (e.g. `"1.1.0: Add foo() function"`). 4. Make sure your `origin` git remote points at the canonical upstream repo (`Postgres-Extensions/extension_tools`, not a personal fork) — @@ -106,3 +109,13 @@ deliberately deferred for this release. - pgxntool's own `make tag`/`make dist` create a *real* git tag, despite `pgxntool/README.asc` describing the result as a "branch" — that's stale wording in the docs, not current behavior (filed upstream to get fixed). +- **CI doesn't fail on test failures.** `pgxntool/base.mk` has + `.IGNORE: installcheck`, so `make test`/`make installcheck` always report + success to `make` regardless of the actual `pg_regress` result — a run + with every test failing still shows green in GitHub Actions. Confirmed + live: PRs #6 and #7 both had every `pg_regress` test fail + (`cat_tools.routine__parse_arg_types_text` doesn't exist in any released + `cat_tools`; that name only exists on cat_tools' unreleased 0.3.0 branch) + while every CI job reported `"conclusion":"success"`. This needs fixing + upstream in pgxntool, and the `cat_tools` call in `sql/extension_drop.sql` + needs fixing here, before this distribution can actually be released. From 5e39c1bfcd7eb706922d82fc8d6fc6e62cd161c2 Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Thu, 16 Jul 2026 16:46:26 -0500 Subject: [PATCH 4/4] Add README documenting the public function API Also point META's docfile at it, and link the filed pgxntool issue in RELEASE.md's CI-blindness note (Postgres-Extensions/pgxntool#49). --- META.in.json | 2 +- META.json | 1 + README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ RELEASE.md | 7 ++++--- 4 files changed, 53 insertions(+), 4 deletions(-) create mode 100644 README.md diff --git a/META.in.json b/META.in.json index 31284f2..71aa541 100644 --- a/META.in.json +++ b/META.in.json @@ -47,7 +47,7 @@ "abstract": "Run custom commands when an extension is dropped.", "X_comment": "Optional: \"docfile\": filesystem path to document file for extension.", - "docfile": "", + "docfile": "README.md", "X_end": "" } diff --git a/META.json b/META.json index d02cded..ba237c7 100644 --- a/META.json +++ b/META.json @@ -47,6 +47,7 @@ "abstract": "Run custom commands when an extension is dropped.", "X_comment": "Optional: \"docfile\": filesystem path to document file for extension.", + "docfile": "README.md", "X_end": "" } diff --git a/README.md b/README.md new file mode 100644 index 0000000..c38c877 --- /dev/null +++ b/README.md @@ -0,0 +1,47 @@ +# extension_drop + +Run custom commands when an extension is dropped. By default, `DROP +EXTENSION` simply drops all the objects the extension owns; this lets you +register additional SQL to run when a given extension is dropped. + +Requires [cat_tools](https://pgxn.org/dist/cat_tools/) >= 0.2.1. + +## Functions + +None of these are granted to `PUBLIC` except where noted, since +`extension_drop__add`/`extension_drop__update` let the caller register +arbitrary SQL to run later. Grant them to specific roles as needed. + +- `extension_drop__add(extension_name name, sql text) RETURNS void` + Register `sql` to run when `extension_name` is dropped. + +- `extension_drop__update(extension_name name, sql text) RETURNS void` + Replace the SQL registered for `extension_name`. + +- `extension_drop__remove(extension_name name) RETURNS void` + Remove the SQL registered for `extension_name`. + +- `extension_drop__get(extension_name name) RETURNS extension_drop__commands` + Look up the row (`extension_name`, `sql`) registered for `extension_name`. + Granted to `PUBLIC` by default. + +- `extension_drop__sanity_check(ignore name DEFAULT NULL) RETURNS name[]` + Returns the names of extensions that have registered drop commands but no + longer exist. Should always return an empty array; pass an extension name + via `ignore` to exclude it from the check (useful while dropping that + extension). Granted to `PUBLIC` by default. + +- `extension_drop__sanity_assert(ignore name DEFAULT NULL) RETURNS void` + Raises an error if `extension_drop__sanity_check()` (called with the same + `ignore` argument) isn't empty. Granted to `PUBLIC` by default. + +- `extension_drop__repair() RETURNS void` + Deletes any stale rows found by `extension_drop__sanity_check()`. This + should never be needed in normal operation. + +## How it works + +An event trigger (`extension_drop`, on `sql_drop`) fires whenever an +extension is dropped, runs any SQL registered for it via +`extension_drop__add`/`extension_drop__update`, and removes the registration +afterward. diff --git a/RELEASE.md b/RELEASE.md index 07da220..c93afd7 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -116,6 +116,7 @@ deliberately deferred for this release. live: PRs #6 and #7 both had every `pg_regress` test fail (`cat_tools.routine__parse_arg_types_text` doesn't exist in any released `cat_tools`; that name only exists on cat_tools' unreleased 0.3.0 branch) - while every CI job reported `"conclusion":"success"`. This needs fixing - upstream in pgxntool, and the `cat_tools` call in `sql/extension_drop.sql` - needs fixing here, before this distribution can actually be released. + while every CI job reported `"conclusion":"success"`. Filed upstream as + Postgres-Extensions/pgxntool#49; the `cat_tools` call in + `sql/extension_drop.sql` also needs fixing here before this distribution + can actually be released.