Dies ist die Dokumentation für den aktuellen Entwicklungsstand. Wählen Sie eine Version aus dem Menü aus, um die Dokumentation für veröffentlichte Versionen zu sehen seit v0.7.5.

Developer Environment

Voraussetzungen

Diese Anleitung geht davon aus, dass du BookWyrm mit Docker entwickelst. Du musst Docker und docker-compose installieren, bevor du loslegst.

Wenn du zu BookWyrm beiträgst, ohne Docker zu verwenden, würden wir uns freuen, wenn du uns helfen würdest, diese Anleitung zu aktualisieren, damit sie auch eine Hilfestellung enthält, wie eine Entwicklungsumgebung ohne Docker aufgesetzt werden kann.

Entwicklungsumgebung einrichten

Quellcode erhalten

  1. Kopiere den BookWyrm-Quellcode von GitHub. Du kannst einen Fork des Projekts erstellen und dann git clone ausführen, um den Quellcode auf deinen Computer herunterzuladen.
  2. Gehe in das Verzeichnis auf deinem Computer, das den Quellcode enthält. Von jetzt an arbeitest du in diesem Verzeichnis.
  3. Die Entwicklung wird auf dem main-Branch durchgeführt. Stelle also sicher, dass du diesen Branch ausgecheckt hast: git checkout main
  4. Set up your development environment variables file by copying the example environment files (.env.example and .env.dev.example) into new files named .env and env.dev. In der Kommandozeile kannst du das wie folgt tun:
cp .env.example .env
cp .env.dev.example .env.dev

Most environment variables are set in the .env file, used in production, but for some development workflows that is overridden by the env.dev file. When developing for BookWyrm, you will need both files.

Bauen und ausführen

  1. Führe Folgendes über die Kommandozeile aus:
./bw-dev create_secrets # Create the secrets file with random values. You only need to do this once.
./bw-dev dev up --build # Build and start development stack
./bw-dev dev runweb python manage.py admin_code # Shows the admin-code for initial setup. You only need to do this once.
  1. Once the build is complete, you can access the instance at http://localhost:1333. If you have removed the PORT value in .env.dev this will be http://localhost. If you have changed the port, swap out 1333 for the port you are using.
  2. Du kannst nun deinen Administrations-Schlüssel eingeben und einen Administrations-Account anlegen. Ab hier funktioniert alles so, wie es in "BookWyrm betreiben" beschrieben ist.

Wenn du neugierig bist: Das ./bw-dev-Kommando ist ein simples Shell-Script, das verschiedene andere Tools ansteuert. Du könntest es überspringen und direkt docker-compose build oder docker-compose up laufen lassen, wenn du möchtest. ./bw-dev kombiniert diese Aufrufe der Einfachheit halber an einem gemeinsamen Ort. Führe das Skript ohne Argumente aus, um eine Liste der verfügbaren Kommandos zu erhalten, lies die zugehörige Seite in der Dokumentation oder öffne das Skript und sieh genau, was jedes Kommando tut!

Modelle editieren oder erstellen

Wenn du ein Modell änderst oder erstellst, wird sich wahrscheinlich die Datenbankstruktur ändern. Damit diese Änderungen wirksam werden, musst du Djangos makemigrations-Befehl ausführen, um eine neue Django Migrationsdateizu erstellen und dann diese migrieren:

./bw-dev makemigrations
./bw-dev dev migrate

Statische Dateien editieren

Jedes Mal, wenn du CSS oder JavaScript bearbeitest, musst du Djangos collectstatic-Befehl erneut ausführen, damit deine Änderungen wirksam werden:

./bw-dev dev collectstatic

Wenn du yarn installiert hast, kannst du yarn watch:static ausführen, um das vorherige Skript bei jeder Änderung automatisch im Verzeichnis bookwyrm/static ausführen zu lassen.

Run code-linters and formatters

Before submitting patch, you should check ruff and other formatting tools. For those to work nicely, you should make sure you have development web-container and dev-tools build.

./bw-dev dev build # This is needed only once, if you haven't run dev stack previously
./bw-dev dev build dev-tools # This is needed only once and if you change pyproject.toml or Dockerfile

After those commands, you can run formatters and pytest and mypy with bw-dev command:

./bw-dev formatters
./bw-dev mypy
./bw-dev pytest

Run development code behind ngrok or other tunneling/proxy service

In .env.dev:

  1. Wenn du einen Tunneling-Dienst oder Proxy wie ngrok verwendest, ändere die DOMAIN zu der Domain, die du verwendest (z. B. abcd-1234.ngrok-free.app).
  2. If you need to use a particular port other than 1333, change PORT to wanted port (e.g. PORT=1333).

Prüfe, ob du alle notwendigen Einstellungen getroffen hast, bevor du fortfährst.

Wenn du versuchst, deinen Administrations-Account anzulegen, und eine Nachricht siehst, die CSRF verification failed lautet, kann es sein, dass du die Domain oder den Port falsch angegeben hast.

E-Mail (optional)

Wenn du ausprobieren möchtest, E-Mails zu versenden, wirst du passende, echte Werte im Bereich "E-Mail-Konfiguration" angeben müssen. Du musst nichts an der separaten Einstellung EMAIL ändern. These settings are in .env -file