Contributing

Thanks for taking the time to contribute to pg_integrity_checksums.

Reporting bugs and requesting features

Use the GitHub issue templates. For security issues, follow SECURITY.md and do not open a public issue.

Development

Requirements:

  • PostgreSQL 12 or newer with server headers;
  • PGXS;
  • a C compiler;
  • Perl and IPC::Run for the TAP tests.

Build and install:

make PG_CONFIG=/path/to/pg_config
make PG_CONFIG=/path/to/pg_config install

Run the regression tests against a running PostgreSQL instance:

make PG_CONFIG=/path/to/pg_config installcheck

Run the TAP suite:

make PG_CONFIG=/path/to/pg_config installcheck \
     enable_tap_tests=yes PROVE=prove

Use PG_CONFIG for non-default PostgreSQL installations. If the test server is not on the default socket or port, set PGHOST, PGPORT, and PGUSER for make installcheck.

Branches and commits

main is release-ready. Create a short-lived branch for each change:

  • feat/<topic> — new behavior;
  • fix/<topic> — bug fix;
  • docs/<topic> — documentation only;
  • test/<topic> — tests only;
  • refactor/<topic> — behavior-preserving cleanup;
  • ci/<topic> — workflows and tooling;
  • chore/<topic> — maintenance;
  • release/<version> — release preparation.

Use Conventional Commits:

<type>(<scope>): <imperative summary>

Common types: feat, fix, docs, test, refactor, perf, build, ci, chore, revert.

Common scopes: cli, extension, ci, docs, workflow, release, deps.

Examples:

feat(cli): add init and config commands
fix(release): use the cosign bundle format
docs(cli): document configuration validation
ci(actions): pin checkout to a commit SHA
test(cli): cover DSN masking
chore(deps): bump pgx to 5.12.0

Keep the subject in the imperative mood, lowercase, without a trailing period, and under about 72 characters. Put details in the body. Mark a breaking change with ! and a BREAKING CHANGE: footer.

Pull request titles must also use Conventional Commits. Use squash merge so the PR title becomes the commit on main. Do not commit directly to main; the exception is an emergency fix, followed by a normal commit on the next branch.

Tags are created only from main after the relevant CI is green:

  • cli-vX.Y.Z for CLI releases;
  • vX.Y.Z for extension releases.

Pull requests

  • Keep each pull request focused on one change.
  • Add a regression test for every behavior change.
  • Update expected/*.out only after reviewing the actual diff. Run the tests, inspect results/ or regression.diffs, and confirm that the new output is correct.
  • Update README.md and Changes when user-visible behavior changes.
  • If the SQL API changes, add an install script and an upgrade script, and update pg_integrity_checksums.control and META.json.
  • Do not commit build artifacts such as *.o, *.so, or test output.
  • Make sure the code builds without new compiler warnings.
  • Describe how the change was tested and on which PostgreSQL versions.

Logical checksum changes

Logical checksum values are a compatibility boundary: changing them invalidates existing baselines. Do not change the logical format silently. Open an issue first and describe:

  • why the change is necessary;
  • whether it affects table, index, or database checksums;
  • how users should migrate or recompute baselines;
  • which release and version should contain it.

Breaking changes must be called out explicitly in Changes and documented in the README.

Code style

Follow PostgreSQL C style and the conventions already used in pg_integrity_checksums.c. Keep functions focused, remove dead code, and document non-obvious checksum semantics. Prefer clear names over abbreviations.