# Contributing to ProvSQL

Thank you for your interest in contributing to ProvSQL!

## Reporting bugs and requesting features

Please use the [GitHub issue
tracker](https://github.com/PierreSenellart/provsql/issues).  Two
issue templates are provided and will auto-fill when you open a new
issue: a bug-report form that asks for the information we typically
need (PostgreSQL version, ProvSQL version, a minimal SQL reproducer,
and optional verbose-mode output) and a feature-request form.  For
security vulnerabilities, please use the [private security
advisory](https://github.com/PierreSenellart/provsql/security/advisories/new)
flow instead of a public issue — see [SECURITY.md](SECURITY.md).

## Developer guide

The [developer
guide](https://provsql.org/docs/dev/introduction.html) is the
authoritative reference for working on ProvSQL's internals. It
covers the PostgreSQL extension concepts ProvSQL relies on, the
architecture and component map, the query rewriting pipeline,
memory management, the where-provenance and data-modification
subsystems, aggregation, semiring and probability evaluation,
coding conventions, testing, debugging, and the build system. Read
it before submitting a non-trivial pull request.

## Development setup

**Prerequisites:** PostgreSQL ≥ 10 with development headers, a C++17 compiler,
`uuid-ossp`, and the Boost libraries (`libboost-dev`,
`libboost-serialization-dev`). See the [installation
guide](https://provsql.org/docs/user/getting-provsql.html) for details.

```sh
make            # build the extension
make install    # install into the PostgreSQL extensions directory
```

ProvSQL requires `shared_preload_libraries = 'provsql'` in
`postgresql.conf` (and a server restart) because it installs a planner hook.

For a debug build:

```sh
make DEBUG=1
```

The [build system
chapter](https://provsql.org/docs/dev/build-system.html) of the
developer guide documents the Makefile structure, the generated
SQL files, and the CI workflows in detail.

## Running the tests

Tests are integration tests against a live PostgreSQL instance:

```sh
make install    # as a user with write access to the PostgreSQL directories
service postgresql restart
make test
```

The [testing
chapter](https://provsql.org/docs/dev/testing.html) explains how
to write a new test, the schedule files, the alternative-output
skip pattern for tests that depend on optional external tools,
and how to read regression diffs.

## Contributing to ProvSQL Studio

ProvSQL Studio (`studio/`, distributed on PyPI as `provsql-studio`)
is a Flask + JavaScript web UI that lives alongside the extension
in this repository. Studio has its own test suite, lint
configuration, and release pipeline, all separate from the
extension's. See the [Studio architecture
chapter](https://provsql.org/docs/dev/studio.html) of the
developer guide for the source-code map, the HTTP API surface,
and the test harness layout.

```sh
# One-off setup: a venv with Studio + its [test] extras and the
# Playwright browser binary.
python3 -m venv studio/.venv
studio/.venv/bin/pip install -e "studio[test]"
studio/.venv/bin/playwright install --with-deps chromium

# Run lint + the unit suite + the Playwright e2e smoke (against the
# extension already installed on your local PostgreSQL).
make studio-test
```

`make studio-test` chains `ruff check .` before `pytest tests`, so
the same lint that gates CI also gates the local target. The
release pipeline is documented in the [build-system
chapter](https://provsql.org/docs/dev/build-system.html#studio-releases).

## Code organization

The codebase mixes C and C++:

- PostgreSQL interface code: C (`src/*.c`)
- Data structures and algorithms: C++ (`src/*.cpp`)
- Generic template algorithms: header-only (`src/*.hpp`)

SQL API is defined in `sql/provsql.common.sql` (and
`sql/provsql.14.sql` for PostgreSQL ≥ 14). Both `sql/provsql.sql`
and `sql/provsql--<version>.sql` are generated by the Makefile —
do not edit them directly. Hand-written extension upgrade scripts
live in `sql/upgrades/provsql--<from>--<to>.sql`; the [build
system chapter](https://provsql.org/docs/dev/build-system.html#extension-upgrades)
of the developer guide explains when and how to write them, and
documents the on-disk mmap ABI that upgrades rely on.

The [architecture
chapter](https://provsql.org/docs/dev/architecture.html) lists
every source file in `src/` with a one-line description, grouped
by subsystem.

## Coding conventions

ProvSQL has a small set of project-specific conventions for
naming, error reporting, memory management, the C/C++ boundary,
and Doxygen comments. They are collected in the [coding
conventions
chapter](https://provsql.org/docs/dev/coding-conventions.html).
The most load-bearing one: every new function, type, class, and
SQL function should carry a JavaDoc-style Doxygen comment, and
new cross-references from the developer guide should be added to
the appropriate map in `doc/source/conf.py` so the coherence
checker can validate them.

## Submitting a pull request

1. Fork the repository and create a branch from `master`.
2. Make your changes. If adding a new feature or fixing a bug:
   - **Extension**: add a regression test in `test/sql/` with
     expected output in `test/expected/`, registered in
     `test/schedule.common` (or `test/schedule.14`).
   - **Studio**: add a unit test under `studio/tests/` or a
     Playwright smoke under `studio/tests/e2e/` that exercises
     the changed behaviour.
3. Ensure the relevant local test target passes: `make test` for
   extension changes, `make studio-test` for Studio changes (or
   both if the change crosses the boundary).
4. If your change touches the documentation, run `make docs` and
   confirm the coherence checker (`check-doc-links.py`) reports
   `OK`.
5. Open a pull request against `master` with a clear description of what the
   change does and why. Do **not** modify either `CHANGELOG.md`
   (extension) or `studio/CHANGELOG.md` (Studio): both are
   maintained at release time. Use the PR description itself to
   describe user-visible changes; that is what the maintainer
   draws from when assembling release notes.

CI runs on Linux (PostgreSQL 10–18), macOS, and WSL for the
extension, and on a Py 3.10/3.11/3.12/3.13 × PG 14/15/16 matrix
for Studio. Failures on any applicable workflow block merging.

## License

By contributing, you agree that your contributions will be licensed under the
[MIT License](LICENSE).