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 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
+    $ 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 PostgreSQL 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 "export 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

docs/discussions.rst

@@ -208,10 +208,10 @@ and an asynchronous code:
   we decided to do.
 
 We've even cheated a bit: instead of implementing our synchronous wrappers manually,
-we've been using a trick that autogenerates a synchronous API based on our asynchronous
-API. This way, we have less code to unit-test, and we can guarantee that the 2 APIs
-will stay synchronized in the future no matter what. Want to know more about this?
-Here are a few resources:
+we've been using a trick that automatically generates a synchronous API based on our
+asynchronous API. This way, we have less code to unit-test, and we can guarantee that
+the 2 APIs will stay synchronized in the future no matter what. Want to know more about
+this? Here are a few resources:
 
 - How we generate our sync API:
   https://github.com/peopledoc/procrastinate/blob/master/procrastinate/utils.py

docs/spelling_wordlist.txt

@@ -1,16 +1,19 @@
+admin
+app
 async
 asynchronicity
 backend
 backoff
+builtin
 codebase
 codebases
 cron
 crons
 Dramatiq
 enqueued
 formatters
+linting
 middleware
-Postgres
 quickstart
 reimplement
 sync

pre-commit-hook

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

procrastinate/aiopg_connector.py

@@ -67,7 +67,7 @@ def interrupt_wait(connection: aiopg.Connection):
 class PostgresJobStore(store.BaseJobStore):
     """
     Uses ``aiopg`` to establish an asynchronous
-    connection to a Postgres database.
+    connection to a PostgreSQL database.
     """
 
     def __init__(self, *, socket_timeout: float = store.SOCKET_TIMEOUT, **kwargs: Any):

procrastinate/testing.py

@@ -23,7 +23,7 @@ def __init__(self):
         """
         Attributes
         ----------
-        jobs : Dict[int, Dict]
+        jobs : ``Dict[int, Dict]``
             Mapping of ``{<job id>: <Job database row as a dictionary>}``
         """
         self.reset()

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

tox.ini

@@ -54,4 +54,7 @@ commands =
     sphinx-build -EW -b spelling docs docs/_build/html {posargs}
     doc8 docs
     # wordlist should be sorted to avoid duplicates
-    sort -c docs/spelling_wordlist.txt
+    # If this line breaks, fix with:
+    # sort -bdfi docs/spelling_wordlist.txt -o docs/spelling_wordlist.txt
+    sort -cbdfi docs/spelling_wordlist.txt
+