Contributing

After completing installation, and running the basic local deployment... you may be wondering: How do I start contributing new code?

Note

All the information in this Wiki page should be enriched with your own reading of documentation and tutorials of both Python and Django development. This is just meant to clarify some details and work as a quick-start for onboarding new developers.

Some docs:

• Django: https://docs.djangoproject.com/en/latest/
• REST: https://www.django-rest-framework.org/api-guide/views/
• DjangoClassViews: https://ccbv.co.uk/
• REST-API: https://www.cdrf.co/3.14/
• DjangoForms: https://cdf.9vo.lt

Please note that to see what a Makefile rule (and all of its dependent rules) is about to do, you can execute them first in "dry run" mode by adding -n. For example: make -n env-setup-dev.

Dependencies

Before proceeding, please check which Python version you're using, issuing the command python -V. It should match one of the versions supported by the application, listed in the output of: grep python-version .github/workflows/django.yml. If you need to install a different python version, do so before creating the environment.

If the version you saw was 2.7, consider using python3 -V, and adjust accordingly all the commands in our Wiki and Makefile. Dealing with Python version(s) and environments varies from developer to developer, and their platforms (Windows for example may use Anaconda). This is beyond the scope of this document.

There are two python packages that should be available in your shell: pip-compile-multi, and pre-commit. Let's call these, "developer dependencies" and differentiate them from our Django application dependencies. Both are installable with pip, and the recommended way is to use a virtual environment (either pip + venv, or conda). Both of these packages are optional, and not required at all for most Contributors.

• We're using pip-compile-multi to generate requirements *.txt files. This allows updating dependencies, or adding new dependencies if it's required. If you needed to add new dependencies to the requirements/*.txt files, please do so by the means of the *.in files and use the pip-compile-multi tool to "compile" (lock version numbers) to the *.txt file(s).

• Also, we are using pre-commit, please remember to install the tool and the hook after cloning the repo so that all the scripts (e.g. Black code formatter) are run before any code is added to an actual commit.

If python -V matches one of the currently supported versions, run make env-setup-dev to install both pre-commit and pip-compile-multi under a python virtual environment, in the root of the repo, and on a path that's already added to the git ignore. For this rule to work, in some distros you'll need python3-venv package (of course, package name varies between OS/ platforms/ distro/ ...)

After installing the packages, you'll also need to install the git hook. Do so by running pre-commit install from the repo root directory.

The Django application dependencies are recommended to be dealt with Docker, but this is optional. If you prefer not to use Docker, you may install all the application dependencies (parkour_app/requirements/dev.txt) in the same environment that has the developer dependencies.

Run Parkour2 locally

First, activate your "developer environment" (containing tools described in the previous section) with source ./env_dev/bin/activate. Then...

With Docker

Use make dev-easy schema, and then run manage.py createsuperuser (inside the container, of course). All your changes to the code will be automatically reloaded, for live debugging. If you encounter errors during your work, a shell is available thanks to Werkzeug. Use make get-pin when opening a python debugging shell on the web browser.

Be sure to check make help to see management commands readily available.

Without Docker

You can also work without Docker, for that you'd need to $ export DJANGO_SETTINGS_MODULE=wui.settings.dev. And create a python virtual environment with all the dependencies from parkour_app/requirements/dev.txt. For this, you may reuse the recently created virtual environment, activate it and run pip install -r parkour_app/requirements/dev.txt (it's adding extra packages on top of the production dependencies). Finally, load the environmental variables (e.g. with set +a; source misc/parkour.env; set -a), and run the server with python parkour_app/manage.py runserver_plus 0.0.0.0:8000...

Or, to run the tests:

python parkour_app/manage.py makemigrations --no-input --check --dry-run
python -Wa parkour_app/manage.py test --buffer --failfast

Debugging

In either case, use raise RuntimeError in a new line, wherever you want to start the debugger (e.g. under the definition of some API endpoint), and then navigate to the appropriate URLs to execute such code. Any errors will be caught by Werkzeug (already set by the command runserver_plus), also all code changes are automatically reloaded in this dev.py mode. Check make get-pin to grab the 6-digit that allows you to open the REPL shell within the browser as an end-user.