diff --git a/HISTORY.asc b/HISTORY.asc new file mode 100644 index 0000000..f483708 --- /dev/null +++ b/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. diff --git a/META.in.json b/META.in.json index c118711..71aa541 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", @@ -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" } }, diff --git a/META.json b/META.json index 42ba119..ba237c7 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", @@ -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" } }, 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 new file mode 100644 index 0000000..c93afd7 --- /dev/null +++ b/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 + `== ` 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. + **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..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. + - 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.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 `../-.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//` (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.