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

If python -V matches one of the currently supported versions, you're good to go. Either way, we recommend using uv, after installing it, run make env-setup-dev.

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

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.