From fd87d5d90f4ccd71f6fc9b3ba22e50b3e7be06b9 Mon Sep 17 00:00:00 2001
From: "Joshua D. Drake" <jd@commandprompt.com>
Date: Wed, 26 Aug 2026 12:55:46 -0600
Subject: [PATCH] Add META.json and a dist target for PGXN

PGXN is the right distribution channel for a PostgreSQL extension, and it
needs a spec 1.0.0 META.json at the root of the release archive. Describe
the distribution there: version 2.5.0, the four extensions it provides
(plruby plus the jsonb, hstore, and ltree transforms, each with its own
version from its .control file), the PostgreSQL 11 floor, and the
repository and bug tracker links.

"make dist" builds the upload archive with git archive, taking the version
from META.json so the two cannot drift, and expanding into a single
plruby-<version>/ directory as PGXN Manager expects. INSTALL documents the
release step and the fields to keep in step when cutting a version.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .gitignore |  3 +++
 INSTALL    | 17 +++++++++++++
 META.json  | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 Makefile   | 11 +++++++++
 4 files changed, 101 insertions(+)
 create mode 100644 META.json

diff --git a/.gitignore b/.gitignore
index 32793a8..8d951c6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,3 +9,6 @@ results/
 regression.diffs
 regression.out
 *.diff
+
+# PGXN release archives
+plruby-*.zip
diff --git a/INSTALL b/INSTALL
index 630da97..d6ee7c4 100644
--- a/INSTALL
+++ b/INSTALL
@@ -71,3 +71,20 @@ and TRANSFORM FOR TYPE ltree (Ruby Array of label Strings):
 
 All three accept the same PG_CONFIG/RUBY overrides and have their own
 "make installcheck".
+
+6. Packaging for PGXN (maintainers)
+-----------------------------------
+
+META.json describes the distribution for PGXN (https://pgxn.org): its version,
+the four extensions it provides, and where the sources live.  Build the release
+archive from a committed tree with:
+
+    make dist
+
+That writes plruby-<version>.zip, taking the version from META.json, and the
+archive expands into a single plruby-<version>/ directory, which is the shape
+PGXN Manager expects at https://manager.pgxn.org/upload.
+
+When cutting a release, keep the "version" field in META.json in step with
+plruby.control and the CHANGELOG, and the "provides" versions in step with the
+per-extension .control files.
diff --git a/META.json b/META.json
new file mode 100644
index 0000000..61bf786
--- /dev/null
+++ b/META.json
@@ -0,0 +1,70 @@
+{
+   "name": "plruby",
+   "abstract": "Ruby as a procedural language for PostgreSQL",
+   "description": "PL/Ruby is a procedural language handler that embeds an MRI Ruby interpreter in the PostgreSQL backend, so functions, set-returning functions, triggers, event triggers, and procedures can be written in Ruby. Arguments and results are converted to and from native Ruby values, including nested Arrays and composites as Hashes, and numeric as a lossless String. Database access is provided through SPI (queries, prepared statements, cursors, transaction control, and subtransactions). The distribution also ships three optional TRANSFORM FOR TYPE extensions for jsonb, hstore, and ltree. PL/Ruby is untrusted: Ruby has no sandbox since 3.0 removed $SAFE, so the extension is superuser-only to install.",
+   "version": "2.5.0",
+   "maintainer": [
+      "Joshua D. Drake <jd@commandprompt.com>"
+   ],
+   "license": "mit",
+   "provides": {
+      "plruby": {
+         "abstract": "Ruby as a procedural language for PostgreSQL",
+         "file": "plruby--2.5.sql",
+         "docfile": "doc/plruby.md",
+         "version": "2.5.0"
+      },
+      "jsonb_plruby": {
+         "abstract": "Transform between jsonb and native Ruby data",
+         "file": "jsonb_plruby/jsonb_plruby--1.0.sql",
+         "version": "1.0.0"
+      },
+      "hstore_plruby": {
+         "abstract": "Transform between hstore and Ruby Hashes",
+         "file": "hstore_plruby/hstore_plruby--1.0.sql",
+         "version": "1.0.0"
+      },
+      "ltree_plruby": {
+         "abstract": "Transform between ltree and Ruby Arrays",
+         "file": "ltree_plruby/ltree_plruby--1.0.sql",
+         "version": "1.0.0"
+      }
+   },
+   "prereqs": {
+      "runtime": {
+         "requires": {
+            "PostgreSQL": "11.0.0"
+         }
+      }
+   },
+   "resources": {
+      "homepage": "https://github.com/commandprompt/plruby",
+      "bugtracker": {
+         "web": "https://github.com/commandprompt/plruby/issues"
+      },
+      "repository": {
+         "url": "https://github.com/commandprompt/plruby.git",
+         "web": "https://github.com/commandprompt/plruby",
+         "type": "git"
+      }
+   },
+   "generated_by": "Joshua D. Drake",
+   "tags": [
+      "ruby",
+      "mri",
+      "procedural language",
+      "plruby",
+      "stored procedures",
+      "triggers",
+      "spi",
+      "transform",
+      "jsonb",
+      "hstore",
+      "ltree"
+   ],
+   "meta-spec": {
+      "version": "1.0.0",
+      "url": "https://pgxn.org/meta/spec.txt"
+   },
+   "release_status": "stable"
+}
diff --git a/Makefile b/Makefile
index c709ae4..42c0e0e 100644
--- a/Makefile
+++ b/Makefile
@@ -39,3 +39,14 @@ REGRESS = init base types numspecial bytea composite encoding datetime jsonb mis
 PG_CONFIG ?= pg_config
 PGXS := $(shell $(PG_CONFIG) --pgxs)
 include $(PGXS)
+
+# Release archive for PGXN (https://pgxn.org).  The version is read from
+# META.json so it cannot drift from the distribution metadata; the archive
+# holds the committed tree, so commit (and tag) before building it.
+DIST_VERSION := $(shell grep -m1 '"version"' META.json | sed -e 's/[^0-9.]//g')
+
+.PHONY: dist
+dist:
+	git archive --format=zip --prefix=plruby-$(DIST_VERSION)/ \
+	    -o plruby-$(DIST_VERSION).zip HEAD
+	@echo "wrote plruby-$(DIST_VERSION).zip"