A pass on the contributing doc

CONTRIBUTING.rst

@@ -3,35 +3,91 @@ Contributing
 
 You're welcome to come and procrastinate with us :)
 
+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)
+
+.. code-block:: console
+
+    $ # Export libpq env vars for PG connection
+    $ export PGDATABASE=procrastinate PGHOST=localhost PGUSER=postgres
+
+    $ # Launch Postgres 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
+    $ export PROCRASTINATE_APP=procrastinate_demo.app.app
+    $ procrastinate -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.
+
+.. code-block:: console
+
+    $ export PGDATABASE=procrastinate PGHOST=localhost PGUSER=postgres
+
 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.
+
 .. code-block:: console
 
-    $ sudo apt install postgresql-client
     $ docker-compose up -d
-    $ export PGDATABASE=procrastinate PGHOST=localhost PGUSER=postgres
+
+If you want to try out the project locally, it's useful to have postgresql-client
+installed. It will give you both a postgres console (``psql``) and specialized
+commands like `createdb` we use below.
+
+.. code-block:: console
+
+    $ sudo apt install postgresql-client
     $ createdb
 
 Set up your development environment
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-You may need to install some required packages for ``psycopg2``:
+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:
 
 .. code-block:: console
 
-    # Ubuntu:
-    $ apt install libpq-dev python-dev
+    $ pip install --user tox
 
-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``:
+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:
 
 .. code-block:: console
 
-    $ pip install tox
+    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:
@@ -40,6 +96,18 @@ dependencies in a virtual environment:
 
     $ python3 -m venv .venv
     $ source .venv/bin/activate
+
+You can check that your Python environment is properly activated:
+
+.. code-block:: console
+
+    (venv) $ which python
+    /path/to/current/folder/.venv/bin/python
+
+Install local dependencies:
+
+.. code-block:: console
+
     (venv) $ pip install -r requirements.txt
 
 Run the project automated tests
@@ -57,7 +125,12 @@ Or
 
     $ tox  # Run all the checks for all the interpreters
 
-If you don't know Tox_, have a look at their documentation, it's a very nice tool.
+If you're not familiar with Pytest_, do yourself a treat and look into this fabulous
+tool.
+
+.. _Pytest: https://docs.pytest.org/en/latest/
+
+If you don't know Tox_, have a look at their documentation, it's a very nice tool too.
 
 .. _Tox: https://tox.readthedocs.io/en/latest/
 
@@ -88,6 +161,28 @@ don't have to, but... Learn it, it's really cool !
 
 .. _`interactive rebase`: https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History
 
+You can also install a `pre-commit`
+hook which makes sure that all your commits are created clean:
+
+.. code-block:: console
+
+    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``:
+
+.. code-block:: bash
+
+    #!/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
 ^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -136,4 +231,8 @@ Wait, there are ``async`` and ``await`` keywords everywhere!?
 -------------------------------------------------------------
 
 Yes, in order to provide both a synchronous **and** asynchronous API, Procrastinate
-needs to be asynchronous at core. Find out more in the Discussions section.
+needs to be asynchronous at core. Find out more in the documentation, in the Discussions
+section. If you need informations on how to work with asynchronous Python, check out:
+
+- The official documentation: https://docs.python.org/3/library/asyncio.html
+- A more accessible guide by Brad Solomon: https://realpython.com/async-io-python/

MANIFEST.in

@@ -6,5 +6,6 @@ exclude CONTRIBUTING.rst
 exclude CODE_OF_CONDUCT.md
 exclude docker-compose.yml
 exclude tox.ini
+exclude pre-commit-hook
 recursive-include procrastinate *.sql
 include LICENSE.rst

pre-commit-hook

@@ -0,0 +1,3 @@
+#!/bin/bash -eu
+
+tox -e check-lint

setup.cfg

@@ -32,6 +32,7 @@ install_requires =
 
 [options.extras_require]
 dev =
+    tox
     black
     isort
 
@@ -63,12 +64,10 @@ include =
     procrastinate
     procrastinate.*
 
-
 [options.entry_points]
 console_scripts =
     procrastinate = procrastinate.cli:main
 
-
 [isort]
 multi_line_output=3
 include_trailing_comma=True