Contributing guidelines

Wanna contribute to Patroni? Yay - here is how!

Chatting

Just want to chat with other Patroni users? Looking for interactive troubleshooting help? Join us on channel #patroni in the PostgreSQL Slack.

Running tests

Requirements for running behave tests:

  1. PostgreSQL packages need to be installed.

  2. PostgreSQL binaries must be available in your PATH. You may need to add them to the path with something like PATH=/usr/lib/postgresql/11/bin:$PATH python -m behave.

  3. If you’d like to test with external DCSs (e.g., Etcd, Consul, and Zookeeper) you’ll need the packages installed and respective services running and accepting unencrypted/unprotected connections on localhost and default port. In the case of Etcd or Consul, the behave test suite could start them up if binaries are available in the PATH.

Install dependencies:

# You may want to use Virtualenv or specify pip3.
pip install -r requirements.txt
pip install -r requirements.dev.txt

After you have all dependencies installed, you can run the various test suites:

# You may want to use Virtualenv or specify python3.

# Run flake8 to check syntax and formatting:
python setup.py flake8

# Run the pytest suite in tests/:
python setup.py test

# Run the behave (https://behave.readthedocs.io/en/latest/) test suite in features/;
# modify DCS as desired (raft has no dependencies so is the easiest to start with):
DCS=raft python -m behave

Testing with tox

To run tox tests you only need to install one dependency (other than Python)

pip install tox>=4

If you wish to run behave tests then you also need docker installed.

Tox configuration in tox.ini has “environments” to run the following tasks:

  • lint: Python code lint with flake8

  • test: unit tests for all available python interpreters with pytest, generates XML reports or HTML reports if a TTY is detected

  • dep: detect package dependency conflicts using pipdeptree

  • type: static type checking with pyright

  • black: code formatting with black

  • docker-build: build docker image used for the behave env

  • docker-cmd: run arbitrary command with the above image

  • docker-behave-etcd: run tox for behave tests with above image

  • py*behave: run behave with available python interpreters (without docker, although this is what is called inside docker containers)

  • docs: build docs with sphinx

Running tox

To run the default env list; dep, lint, test, and docs, just run:

tox

The test envs can be run with the label test:

tox -m test

The behave docker tests can be run with the label behave:

tox -m behave

Similarly, docs has the label docs.

All other envs can be run with their respective env names:

tox -e lint
tox -e py39-test-lin

It is also possible to select partial env lists using factors. For example, if you want to run all envs for python 3.10:

tox -f py310

This is equivalent to running all the envs listed below:

$ tox -l -f py310
py310-test-lin
py310-test-mac
py310-test-win
py310-type-lin
py310-type-mac
py310-type-win
py310-behave-etcd-lin
py310-behave-etcd-win
py310-behave-etcd-mac

You can list all configured combinations of environments with tox (>=v4) like so

tox l

The envs test and docs will attempt to open the HTML output files when the job completes, if tox is run with an active terminal. This is intended to be for benefit of the developer running this env locally. It will attempt to run open on a mac and xdg-open on Linux. To use a different command set the env var OPEN_CMD to the name or path of the command. If this step fails it will not fail the run overall. If you want to disable this facility set the env var OPEN_CMD to the : no-op command.

OPEN_CMD=: tox -m docs

Behave tests

Behave tests with -m behave will build docker images based on PG_MAJOR version 11 through 15 and then run all behave tests. This can take quite a long time to run so you might want to limit the scope to a select version of Postgres or to a specific feature set or steps.

To specify the version of postgres include the full name of the dependent image build env that you want and then the behave env name. For instance if you want Postgres 15 use:

tox -e pg14-docker-build,pg14-docker-behave-etcd-lin

If on the other hand you want to test a specific feature you can pass positional arguments to behave. This will run the watchdog behave feature test scenario with all versions of Postgres.

tox -m behave -- features/watchdog.feature

Of course you can combine the two.

Reporting issues

If you have a question about patroni or have a problem using it, please read the README before filing an issue. Also double check with the current issues on our Issues Tracker.

Contributing a pull request

  1. Submit a comment to the relevant issue or create a new issue describing your proposed change.

  2. Do a fork, develop and test your code changes.

  3. Include documentation

  4. Submit a pull request.

You’ll get feedback about your pull request as soon as possible.

Happy Patroni hacking ;-)