# Publishing a PostgreSQL extension

This is the checklist for releasing `jev`. It doubles as a guide to how PostgreSQL extensions reach developers.

## Where developers get extensions

| Channel | What it is | How they install |
| --- | --- | --- |
| **GitHub / git** | Source of truth. `make install` via PGXS works on any machine with `pg_config`. | `git clone … && make install` |
| **PGXN** (pgxn.org) | The PostgreSQL Extension Network: a CPAN-style index of source distributions. Requires a (free, manually approved) account at manager.pgxn.org. | `pgxn install jev` |
| **Trunk** (pgt.dev) | Pre-built binaries per PG version; used by Tembo and others. Optional. | `trunk install jev` |
| **pgxman** | apt-style packages for extensions. Optional. | `pgxman install jev` |
| **Docker image** | Easiest way to try it. Publish to GHCR or Docker Hub. | `docker run ghcr.io/realzachi/pg-jev` |
| **Distro / PGDG packages** | Debian/RPM packages in apt.postgresql.org and yum.postgresql.org. Ask the PGDG packagers on the pgsql-pkg lists once the project is stable. | `apt install postgresql-16-jev` |
| **Managed providers** | RDS, Cloud SQL, Neon, Supabase etc. each curate their own allow-list. Only reachable by request, and `plpython3u` is not allowed on most of them. | – |

For a PL/Python extension like this one there is nothing to compile, so the source distribution *is* the
binary: PGXN plus a Docker image covers nearly everyone.

## Release checklist

1. **Version bump.** Update `default_version` in `jev.control`, rename/add `sql/jev--X.Y.Z.sql`, add an upgrade
   script `sql/jev--OLD--NEW.sql` if the SQL objects changed, update `jev_version()`, `META.json`, `CHANGELOG.md`.
2. **Test.** `make docker-test PG_MAJOR=14` … `17`. CI does the same on every push.
3. **Check the bundle.** `docker run --rm --platform linux/amd64 -v "$PWD":/repo -w /repo pgxn/pgxn-tools pgxn-bundle`
   validates `META.json` and writes `jev-X.Y.Z.zip` (same content as `make dist`; `.gitattributes` keeps
   `.agents`, `.claude`, `.github` and dotfiles out of it). Note that `git archive` reads `.gitattributes` from the
   commit, so those rules have to be committed to take effect.
4. **Tag.** `git tag -a vX.Y.Z -m "jev X.Y.Z" && git push origin vX.Y.Z`. The release workflow attaches the zip
   to a GitHub release and, when the `PGXN_USERNAME` / `PGXN_PASSWORD` repository secrets are set, uploads it to
   PGXN with `pgxn-release`. The distribution appears at https://pgxn.org/dist/jev/ within minutes and is then
   installable with `pgxn install jev`.
   Manual alternative: upload the zip at https://manager.pgxn.org/upload. A version can only be released once;
   fixing a published release means bumping the version.
5. **Docker.** `docker build -t ghcr.io/realzachi/pg-jev:X.Y.Z-pg16 --build-arg PG_MAJOR=16 .` for each supported
   major, push, and add `latest`.
6. **Announce.** pgsql-announce@lists.postgresql.org (moderated, extensions welcome), the PostgreSQL
   Slack/Discord `#extensions`, and the TypeSafe community.

## What a good extension repo has

- `EXTENSION.control` + `sql/EXTENSION--VERSION.sql`, versioned, with upgrade scripts between releases.
- A PGXS `Makefile` so `make install` and `make installcheck` just work.
- `META.json` (PGXN spec 1.0.0) with abstract, license, provides, prereqs and resources.
- An OSI license. PostgreSQL License and MIT are the norm in this ecosystem.
- Regression tests (`pg_regress`) that don't depend on network or secrets.
- CI across all supported PostgreSQL majors.
- README covering install, every function and setting, security notes, and cost.
- CHANGELOG, CONTRIBUTING, and a clear statement of which PostgreSQL versions are supported.