Contributing

Let’s head north, welcome to Septentrion!

This contributing guide is trying to avoid common pitfalls, but the project development environment is quite common. If it’s not your first rodeo, here’s a TL;DR

TL;DR

(The following is not meant to be executed as a script)

$ # Export libpq env vars for PG connection
$ export PGDATABASE=septentrion PGHOST=localhost PGUSER=postgres PGPASSWORD=password

$ # Launch PostgreSQL within Docker
$ compose up -d

$ # Explore tox entrypoints
$ tox -l

$ # You can do things without tox too:

$ # Install requirements
$ pip install -r requirements.txt

$ # Launch tests
$ pytest

$ # Launch demo
$ septentrion -h

Instructions for contribution

Environment variables

The export command below will be necessary whenever you want to interact with the database (using the project locally, launching tests, …). These are standard libpq environment variables, and the values used below correspond to the docker setup. Feel free to adjust them as necessary.

$ export PGDATABASE=septentrion PGHOST=localhost PGUSER=postgres PGPASSWORD=password

Create your development database

The development database can be launched using docker with a single command. The PostgreSQL database we used is a fresh standard out-of-the-box database on the latest stable version.

$ docker-compose up -d

If you want to try out the project locally, it’s useful to have postgresql-client installed. It will give you both a PostgreSQL console (psql) and specialized commands like createdb we use below.

$ sudo apt install postgresql-client
$ createdb

Set up your development environment

If you don’t plan to run the code interactively and just want to run tests, linting and build the doc, you’ll just need tox. You can install it for your user:

$ pip install --user tox

In order for this to work, you’ll need to make sure your python user install binary directory is included in your shell’s PATH. One way of doing that is to add a line in your ~/.profile (or ~/.zprofile for zsh). The following command will output the line to write in that file:

echo 'PATH=$(python3 -c "import site; print(site.USER_BASE)")/bin:$PATH'

If you plan to launch the project locally, install the package itself with development dependencies in a virtual environment:

$ python3 -m venv .venv
$ source .venv/bin/activate

You can check that your Python environment is properly activated:

(venv) $ which python
/path/to/current/folder/.venv/bin/python

Install local dependencies:

(venv) $ pip install -r requirements.txt

Run the project automated tests

With a running database:

(venv) $ pytest  # Test the code with the current interpreter

Or

$ tox  # Run all the checks for all the interpreters

If you’re not familiar with Pytest, do yourself a treat and look into this fabulous tool.

If you don’t know Tox, have a look at their documentation, it’s a very nice tool too.

To look at coverage in the browser after launching the tests, use:

$ python -m webbrowser htmlcov/index.html

Keep your code clean

Before committing:

$ tox -e format

If you’ve committed already, you can do a “Oops lint” commit, but the best is to run:

$ git rebase -i --exec 'tox -e format' origin/master

This will run all code formatters on each commits, so that they’re clean. If you’ve never done an interactive rebase before, it may seem complicated, so you don’t have to, but… Learn it, it’s really cool !

You can also install a pre-commit hook which makes sure that all your commits are created clean:

cat > .git/hooks/pre-commit <<EOF
#!/bin/bash -e
exec ./pre-commit-hook
EOF
chmod +x .git/hooks/pre-commit

If tox is installed inside your virtualenv, you may want to activate the virtualenv in .git/hooks/pre-commit:

#!/bin/bash -e
source /path/to/venv/bin/activate
exec ./pre-commit-hook

This will keep you from creating a commit if there’s a linting problem.

Build the documentation

Without spell checking:

$ tox -e docs
$ python -m webbrowser docs/_build/html/index.html

Run spell checking on the documentation:

$ sudo apt install enchant
$ tox -e docs-spelling

Because of outdated software and version incompatibilities, spell checking is not checked in the CI, and we don’t require people to run it in their PR. Though, it’s always a nice thing to do. Feel free to include any spell fix in your PR, even if it’s not related to your PR (but please put it in a dedicated commit).

If you need to add words to the spell checking dictionary, it’s in docs/spelling_wordlist.txt. Make sure the file is alphabetically sorted!

Try our demo

With a running database:

(venv) $ export PGDATABASE=septentrion PGHOST=localhost PGUSER=postgres
(venv) $ createdb
(venv) $ export SEPTENTRION_MIGRATIONS_ROOT=example_migrations SEPTENTRION_TARGET_VERSION=1.1
(venv) $ septentrion migrate