Release prep: 1.0.0 stable

HISTORY.asc

@@ -0,0 +1,20 @@
+1.0.0
+-----
+== 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.
+
+== 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.

META.in.json

@@ -28,7 +28,7 @@
     "maintainer": [ "Jim Nasby <Jim.Nasby@OpenSCG.com>" ],
 
     "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",
@@ -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": ""
         }
@@ -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"
         }
     },

META.json

@@ -28,7 +28,7 @@
     "maintainer": [ "Jim Nasby <Jim.Nasby@OpenSCG.com>" ],
 
     "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",
@@ -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": ""
         }
@@ -57,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"
         }
     },

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.

RELEASE.md

@@ -0,0 +1,122 @@
+# 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.
+
+## 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
+    `== <heading>` 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/<ext>.sql`), also maintain the
+  upgrade script from the last released version to `stable`:
+  `sql/<ext>--<last-released-version>--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.
+   **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
+     `version` under `provides.<extension>.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 `<extension>.control`: bump `default_version` to match.
+   - 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/<ext>--<last-released-version>--stable.sql` to
+     `sql/<ext>--<last-released-version>--<new-version>.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:
+   `"<version>: <one-line summary>"` (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) —
+   `make tag` pushes to whatever `origin` is, and a tag pushed to a fork does
+   nothing for PGXN.
+
+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
+     (check `meta.mk` if unsure what `PGXNVERSION` resolved to) — and pushes
+     it to `origin`.
+   - Runs `git archive` at that tag into `../<dist-name>-<version>.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.
+
+   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.
+
+7. Verify the new version shows up at `https://pgxn.org/dist/<name>/` (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 5-6 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 (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"`. 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.