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
(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¶
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
installed. It will give you both a PostgreSQL console (
psql) and specialized
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
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
$ 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¶
$ 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
cat > .git/hooks/pre-commit <<EOF #!/bin/bash -e exec ./pre-commit-hook EOF chmod +x .git/hooks/pre-commit
tox is installed inside your
virtualenv, you may want to activate the
#!/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