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/*.sql against expected/*.out): the SQL surface. Generate expected output from a real run (dev/regress.sh leaves it in results/ under the build directory), read it, then copy it into expected/.
  • 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

  1. Bump default_version in pg_gaps.control and both "version" fields in META.json (make check-meta fails until they agree), and rename the install script as AGENTS.md rule 25 says.
  2. Move CHANGELOG.md’s “Unreleased” section under the new version. Change META.json’s release_status from testing to stable for a release that should be PGXN’s default.
  3. Tag vX.Y.Z and push the tag to GitHub. .github/workflows/release.yml builds make dist (a PGXN-layout pg_gaps-X.Y.Z.zip from git archive; .gitattributes keeps development files out), builds and tests the zip itself, attaches it to a GitHub Release, and uploads it to PGXN with the PGXN_USER and PGXN_PASSWORD repository secrets (skipped with a warning when they are not set).
  4. 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.