CONTRIBUTING.md

How to Develop for SQLSYNTHGEN

The following instructions have been tested on MacOS Ventura, but they should work on other Unix-based OS.

Pre-requisites

Please install the following software on your workstation:

1. Poetry.
2. Pre-commit.
3. PostgreSQL.

Setting up your development environment

1. Clone the GitHub repository:

   git clone https://github.com/alan-turing-institute/sqlsynthgen.git

2. In the directory of your local copy, create a virtual environment with all sqlsynthgen dependencies:

   cd sqlsynthgen
   poetry install --all-extras

   If you don't need to build the project documentation, the --all-extras option can be omitted.

3. Install the git hook scripts. They will run whenever you perform a commit:

   pre-commit install --install-hooks

   To execute the hooks before a commit, run pre-commit run --all-files.

4. Finally, activate the Poetry shell. Now you're ready to play with the code:

   poetry shell

Running unit tests

Executing unit tests is straightforward:

cd sqlsynthgen
python -m unittest discover --verbose tests/

Running functional tests

Functional tests require a PostgreSQL service running. Perform the following steps on your local server:

1. Set the password of user postgres to password:

    psql -p5432 "postgres"
    postgres=# \password postgres
    Enter new password: <password>
    postgres=# \q

2. From the shell, create and load the src database:

   createdb src
   cd sqlsynthgen
   PGPASSWORD=password psql --host=localhost --username=postgres --file=tests/examples/src.dump

   WARNING: Some MacOS systems do not recognise the 'en_US.utf8' locale. As a workaround, replace en_US.utf8 with en_US.UTF-8 on every *.dump file.

3. Also, create dst database:

   createdb dst
   PGPASSWORD=password psql --host=localhost --username=postgres --file=tests/examples/dst.dump

4. Finally, run the functional tests. You will need the environment variable REQUIRES_DB with a value of 1.

   REQUIRES_DB=1 poetry run python -m unittest discover --verbose tests

Building documentation locally

cd docs
make html

WARNING: Some systems won't be able to import the sphinxcontrib.napoleon extension. In that case, please replace sphinxcontrib.napoleon with sphinx.ext.napoleon in docs/source/conf.py.