Contents
Contributing to pg_gaps
Building
pg_gaps builds with PGXS against an installed PostgreSQL 17 or later. You
need a C compiler and the server headers (postgresql-server-dev-*, or a
source install with pg_config).
make PG_CONFIG=/path/to/pg_config
sudo make install PG_CONFIG=/path/to/pg_config
make installcheck PG_CONFIG=/path/to/pg_config # against a running server
make installcheck writes its results into the directory it runs in,
so it fails with “could not create directory” when the source tree is
not writable by the user running it. Use dev/regress.sh, or an
out-of-tree (VPATH) build, which keeps objects and test output out of the
source directory:
mkdir -p /path/to/build && cd /path/to/build
make -f /path/to/pg_gaps/Makefile VPATH=/path/to/pg_gaps
With Nix
nix develop # PostgreSQL 18, clang, make, shellcheck
dev/regress.sh # build out of tree, run the suite on a throwaway cluster
nix flake check # the gate: build + regress on PG 17, 18 and 19
nix build .#pg17 # the extension package for one major
dev/regress.sh needs PostgreSQL 18 or later, because it points the
server at the build’s install tree with extension_control_path instead
of writing into the server’s own prefix. nix flake check covers 17.
Tests
- Regression (
sql/*.sqlagainstexpected/*.out): the SQL surface. Generate expected output from a real run (dev/regress.shleaves it inresults/under the build directory), read it, then copy it intoexpected/. - Oracles: every inference path is checked against brute-force
enumeration of possible worlds on small models, and the exact paths
against pgmpy. These arrive with Phase 2 (
ROADMAP.md).
A change that affects the probabilities returned comes with a test that would have failed before it.
Style
PostgreSQL’s own C conventions: tabs, pgindent-compatible layout, C99
without declarations after statements, snake_case. Read a neighbouring
file when in doubt. No new warnings under the server’s CFLAGS; CI
builds with -Werror. ASCII only in sources and install scripts (make
check-ascii).
The inference core (factor algebra, variable elimination, sampling, Viterbi) is plain C with no PostgreSQL headers, so it can be compiled and tested on its own; keep it that way.
Submitting changes
There is no CLA and no sign-off requirement. By contributing you agree
that your contribution is licensed under the PostgreSQL License
(LICENSE).
Continuous integration
Codeberg (the origin) runs .woodpecker/ci.yaml on Woodpecker
(ci.codeberg.org); GitHub, which mirrors it, runs
.github/workflows/ci.yml. Both build and test against the PGDG packages
of PostgreSQL 17, 18 and 19 through the same script, ci/pgdg.sh, so the
two cannot drift; GitHub also runs nix flake check. Run ci/pgdg.sh
MAJOR in a debian:trixie container to reproduce either locally.
Releasing
- Bump
default_versioninpg_gaps.controland both"version"fields inMETA.json(make check-metafails until they agree), and rename the install script as AGENTS.md rule 25 says. - Move
CHANGELOG.md’s “Unreleased” section under the new version. ChangeMETA.json’srelease_statusfromtestingtostablefor a release that should be PGXN’s default. - Tag
vX.Y.Zand push the tag to GitHub..github/workflows/release.ymlbuildsmake dist(a PGXN-layoutpg_gaps-X.Y.Z.zipfromgit archive;.gitattributeskeeps development files out), builds and tests the zip itself, attaches it to a GitHub Release, and uploads it to PGXN with thePGXN_USERandPGXN_PASSWORDrepository secrets (skipped with a warning when they are not set). - To republish an existing tag, run the workflow by hand
(
workflow_dispatch) with the tag; do not re-tag. PGXN answers 409 for a version it already has.