Development.md

Lokale Entwicklung

Dieses Projekt basiert auf Python 3.13+ und Django 5.1+.

Initiale Einrichtung

Lokales Docker development image

Das Docker development image vereinfacht die initiale Einrichtung und sperrt alle Abhängigkeiten und Prozesse in einen Entwicklungscontainer. Alternativ ist auch eine manuelle Einrichtung möglich.

1. Docker und Docker Compose installieren. Unter Windows getestet mit WSL 2.
2. Klonen dieses Repositories an beliebigen Ort.
3. Image erzeugen: docker compose build
   • Für schnellere Builds kann buildkit verwendet werden:

     export DOCKER_BUILDKIT=1

   • Die Standardpasswöter für PostgreSQL und Hub Benutzer sind in der docker-compose.yml Datei festgelegt und können per Umgebungsvariable angepasst werden.
4. Container erzeugen: docker compose up -d hub
   • Beim Start mittels docker compose wird kein HUB Admin Benutzer angelegt um ein ungewolltes anlegen von diesen Benutzern in der Produktivumgebung vorzubeugen. Falls der admin Benutzer angelegt werden soll muss die Umgebungsvariable DJANGO_CREATE_ADMIN_PASSWORD für den Container gesetzt werden.
5. Optional: Import von Demo-Daten: docker compose exec -it hub python manage.py loaddata ./core/fixtures/anhalter.json

Debug Zugriff

Um auf einen Docker Container mit dem root bentuzer zuzugreifen kann das folgende Kommando verwendet werden: docker compose exec -u root hub /bin/bash

Docker Einstellungen in der Entwicklungsumgebung

Um die Einstellungen der Instanz anzupassen kann eine dev.env Datei im Root-Verzeichnis angelegt werden.

Diese kann duch das anlegen einer localen compose Datei mit dem folgenden Inhalt geladen werden:

version: "3.8"

services:
  hub:
    env_file:
      - dev.env

Diese kann durch das setzen der Umgebungsvariable COMPOSE_FILE=docker-compose.yml:docker-compose.local.yml automatisch beim allen docker compose Kommandos berücksichtigt werden. Um eine andere Demo Datei zu laden kann die Umgebungsvariable DJANGO_LOAD_FIXTURE gesetzt werden (Aufgrund von Compose Prioritäten ist es nicht möglich das über die dev.env Datei zu setzen).

Lokale Einrichtung

1. Installiere, falls noch nicht geschehen, Python in Version 3.13 (oder höher) und habe eine PostgreSQL-Datenbank zur Hand (z.B. aus dem docker mit exposed port). Außerdem wird unter Umständen GNU gettext benötigt, wenn man Übersetzungen kompilieren will. Alternativ kann auch das docker dev image verwendet werden.
   • Linux: Pakete python3, postgresql und gettext
   • Mac: brew install python3 postgresql gettext bzw. https://postgresapp.com/
   • Windows: latest stable Python 3 release und PostgreSQL Installer und gettext binaries
   • Python Paketmanager: pdm: Kann mit OS Installationsmitteln oder mit pip install pdm installiert werden.
2. Klone dieses Repository an beliebigen Ort.
3. Erstelle die virtuelle Umgebung mit pdm info
4. Installiere die python dependencies mit pdm install
5. (falls nicht bereits vorhanden) lege einen PostgreSQL-User an (createuser -P hub_app) sowie eine Datenbank (createdb -O hub_app hub) - unter Linux ggf. via sudo -u postgres
6. Konfiguriere deine Instanz mittels:
   • Umgebungsvariablen (z.B. direnv, oder env Datei)
   • oder mittels einer local_settings.py in src/hub/ an (Dokumentation zur Datenbankkonfiguration in der Django-Dokumentation):

DEBUG = True
ALLOWED_HOSTS = ['127.0.0.1', 'localhost']
SESSION_COOKIE_SECURE = False
SESSION_COOKIE_DOMAIN = None
IS_API = True
IS_FRONTEND = True
EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'  # "send" emails as console output
SELECTED_CONFERENCE_ID = '40ba6cda-1970-409f-81ef-efb87ef09d95' # change this to the id of your conference you want to display in frontend (matches the one from rc3_2020.json)
METRICS_SERVER_IPS = ['127.0.0.1']   # Change this if you want to test the Prometheus / Grafana metrics endpoint (http://127.0.0.1:8000/metrics/)

DATABASES = {
    'default': {
        'ENGINE': 'django.contrib.gis.db.backends.postgis',
        'NAME': 'hub',
        'USER': 'hub_app',
        'PASSWORD': '<kennwort-aus-dem-createuser-aufruf>',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

8. Lege die Datenbanktabellen an: pdm manage migrate
9. Richte einen Admin-Nutzer (für die Anwendung) ein: pdm manage createsuperuser
10. optional: Import von Demo-Daten: pdm manage.py loaddata .src/core/fixtures/rc3_2021.json
11. optional: Für deinen Adminuser via Admin-Seite einen ConferenceMember anlegen um den User für das Frontend freizuschalten

Nutzung

1. Aktiviere das virtual env pdm venv activate
2. Wende ggf. vorhandene DB-Migrations an (wenn du gerade aus dem Git geupdatet hast): pdm manage migrate
3. Stelle sicher dass alle Translations aktuell sind: pdm manage compilemessages
4. Lasse alle staticfiles einsammeln: pdm manage collectstatic
5. Starte den Dev-Server: pdm manage runserver
6. Besuche die lokale Instanz: Admin-Seite, API und plainui-Frontend

PlainUI Development Tipps

CSS Kompilieren (PlainUi)

1. Gehe in das Verzeichnis src/plainui/
2. Führe yarn aus, um die node_modules zu generieren
3. Führe yarn build aus um das CSS zu kompilieren
4. Um das CSS beim Entwickeln automatisch neu zu kompilieren gibt es yarn watch

Components

Wiederverwendbare Elemente können als Komponenten integriert werden. Dafür gibt es jeweils 2 "components"-Ordner. Die HTML-Komponenten befinden sich in plainui/jinja2/plainui/components. Sollten zusätzliche Styles benötigt werden, können diese in plainui/styles/components hinzugefügt werden, welche anschließend in rc3.scss integriert werden. Wichtig ist, ein eigenes File pro Komponente anzulegen. Für Jinja eignen sich dazu Macros oder Includes. Zusätzlich ist die Komponente in der Übersicht hinzuzufügen - lokal erreichbar unter http://localhost:8000/component_gallery.

Python Development Tipps

Abhängigkeitsverwaltung

Zur Verwaltung der verwendeten python Abhängigkeiten wir der Paketmanager PDM verwendet. Mittels diesem werden die requirements.txt und die requirements.dev.txt erzeugt.

Installation der aktuellen Abhängigkeiten

Um die aktuellen python Abhängigkeiten zu installieren kann das Kommando pdm install verwendet werden. Mit dem Kommando pdm sync --clean kann sichergestellt werden, dass genau die Versionen aus dem pdm lock file installiert werden.
Achtung: Nicht in der Lock Datei enthaltene python Pakete werden deinstalliert!

Hinzufügen von neuen Abhängigkeiten

Um neue Abhängigkeiten hinzuzufügen kann das Kommando pdm add verwendet werden. Mit dem Parameter --dev kann eine Abhängigkeit als Entwicklungs-Abhängigkeit deklariert werden. Diese wird dann in den Produktivinstanzen nicht installiert.

Anschließend müssen die requirements.txt und requirements.dev.txt angepasst werden. Wenn pre-commit verwendet wird, passiert dies automatisch beim commit.
Alternativ können die folgenden Kommandos verwendet werden

pdm export --no-hashes -o requirements.txt --prod
pdm export --no-hashes -o requirements.dev.txt --dev

Debugging DJANGO

Context im HTML-File ausgeben:

<pre>{% debug %}</pre>

oder:

<pre>
        {{ show_vars(myContextElement) }}
    </pre
>

Übersetzungen extrahieren & compilieren

• pdm manage makemessages
• Die Übersetzungsdateien in <app>/locale/<sprache>/LC_MESSAGES/django.po wurden um alle neuen Übersetzungsstrings erweitert. Bearbeiten und jeweils bei msgstr die Übersetzungen einfügen!
• pdm manage compilemessages
• Zum Ausprobieren müsst ihr django neu starten um die neuen Übersetzungsdateien zu laden

Übersetzungen definineren

• in Python: gettext wie üblich in Django, siehe Doku
• in jinja2-Templates via _, bspw. {{ _("Settings") }} oder mit Platzhalter {{ _("Hello, %(username)s", username=user.display_name) }}

Static Files einsammeln lassen

• pdm manage collectstatic
• ohne dies brechen u.a. Unittests mit Fehlern wie "Missing staticfiles manifest entry" ab

Tests

Es gibt Django (Unit-)Tests für die einzelnen Apps. Diese finden sich jeweils im tests Ordner der App. Außerdem gibt es im repository root unter tests auch noch einfache Integrationstests.

Test mit Übersetzten Inhalten

Um sicherzustellen, dass Tests mit Übersetzungen in allen Umgebungen funktionieren, müssen die Übersetzungsfunktionen gemocked werden. Dazu gibt es in core.tests.utils eine mocktrans Funktion die alle Text einfach mich _trans ergänzt (z.B. wird aus "Login" dann "Login_trans").

Die Funktion kann dann wie folgt verwendet werden:

with patch('core.models.ticket._', side_effect=mocktrans):
    translation = funktions_aufruf()
self.assertEqual(translation, "NoTIcket_trans")

Django Tests ausführen

Um die Tests ausführen zu können muss der Datenbanknutzer das Recht haben neue Datenbaken anzulegen. Dafür mit psql postgres die Datenbankkonsole starten. Dort ALTER USER hub_app CREATEDB; ausführen (ggf. hub_app durch den gewählten Nutzernamen ersetzen). Am Ende mit Strg-D Konsole wieder schließen.

Um die Django Tests auszuführen kann das Kommando pdm test verwendet werden.
Um nur die Tests einer App auszuführen stattdessen pdm test -- <app>.tests ausführen.
Hilfreiche Argumente sind -v 2 um die ausgeführten Tests anzuzeigen, --failfast um nach dem ersten Fehler abzubrechen, und --keepdb um nicht jedes mal die Migrationen durchführen zu müssen.
Für weitere Infos zu dem Befehl ist https://docs.djangoproject.com/en/3.1/ref/django-admin/#django-admin-test hilfreich.

Um eine Ausführungsgebung zu verwenden die ähnlicher zu der der CI ist, kann DJANGO_SETTINGS_MODULE=hub.settings.ci ./manage.py test verwendet werden.

Django Tests in Docker ausführen

Um alle Tests auszuführen kann das test profil verwendet werden. Hierzu einfach docker compose --profile test run hubtest ausführen. Die oben beschriebenen Funktionen können einfach hinten angehängt werden (z.B. docker compose --profile test run hubtest -v 2 --failtest).

Linting and Formatting

Pre-commit hooks

Um zu verhindern, dass falscher Code eingecheckt wird können pre-commit hooks mittels "pre-commit install" hinzugefügt werden. Ab dann wird vor jedem commit ein Teil der checks (vor allem Format Tests) durchgeführt.

ruff for python

Um das Format und die Korrektheit der python Dateien im Hub sicherzustellen setzen wir das tool ruff ein. Dieses hat die folgenden Kommandos:

• ruff check: Diess Kommando checkt auf häufige Fehler in python code und hat auch teilweise Möglichkeiten diese zu beheben
• ruff format: Dieses Kommando re-formatiert alle python dateien nach einem voregebenen Code-Style

djLink

Leider ist es nicht möglich djLint so zu konfigurieren, dass es automatisch die richtigen Profile verwendet. Wenn eine Integration in einen Editor gewünscht ist, muss dies berücksichtigt werden!

Manuell kann es folgendermaßen ausgeführt werden:

• djlint --profile django --extension html --reformat . um alle .html Dateien zu formatieren
• djlint --profile jinja --extension j2 --reformat . um alle .j2 Dateien zu formatieren
• djlint --lint . um alle ein potenzielle Fehler per Linting zu finden

Häufige Fehler

$ ./manage.py migrate
<snip>
AttributeError: 'DatabaseOperations' object has no attribute 'geo_db_type'

Dieser Fehler tritt auf, wenn man PostGIS-Felder mit dem normalen Django-Postgres-Backend anlegen möchte. Statt dessen als Engine django.contrib.gis.db.backends.postgis verwenden.

Docker Image Abhängigkeiten

Das Bild zeigt die aktuellen Docker Image Abhängigkeiten aus dem Multistage Dockerfile

Recreate image

docker run \
  --rm \
  --user "$(id -u):$(id -g)" \
  --workdir /workspace \
  --volume "$(pwd)":/workspace \
  ghcr.io/patrickhoefler/dockerfilegraph:alpine -o png

Ignore Format Commits

Um den Reformat in lokalen git blame Kommandos zu ignorieren kann man die .git-blame-ignore-revs Datei verwenden. Für dauerhafte Konfiguration bitte das folgende Kommando verwenden:

git config blame.ignoreRevsFile .git-blame-ignore-revs