diff --git a/docs/dev_workflow.md b/docs/dev_workflow.md index 399458a..ddc4f48 100644 --- a/docs/dev_workflow.md +++ b/docs/dev_workflow.md @@ -1,6 +1,6 @@ # Mindnet v2.2 – Entwickler-Workflow **Datei:** `DEV_WORKFLOW.md` -**Stand:** 2025-12-07 +**Stand:** 2025-12-07 (Aktualisiert nach WP-04b) Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server). @@ -27,29 +27,26 @@ Hier erstellst du die neue Funktion in einer sicheren Umgebung. * Unten links in der blauen Leiste sollte der aktuelle Branch stehen (z.B. `main`). 2. **Branch erstellen (WICHTIG):** - * Klicke unten links auf den Branch-Namen (z.B. `main`). - * Wähle im Menü oben `+ Create new branch...`. + * Klicke unten links auf den Branch-Namen. + * Wähle `+ Create new branch...`. * Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp04b-explanation`). * Drücke **Enter**. 3. **Sicherheits-Check:** - * Schau unten links: Steht dort jetzt `feature/wp04b-explanation`? - * **Nur wenn dort dein Feature-Branch steht, darfst du Code ändern!** Alles, was du jetzt speicherst, landet in diesem Branch. + * Steht unten links jetzt dein Feature-Branch? **Nur dann darfst du Code ändern!** 4. **Coden:** * Nimm deine Änderungen vor. 5. **Sichern & Hochladen:** - * Klicke links auf das **Source Control** Icon (Gabel-Symbol). - * Gib eine Nachricht ein: "feat: Add explanation layer logic". - * Klicke auf **Commit**. - * Klicke auf **Publish Branch** (oder "Sync Changes"), um den Branch zum Raspberry Pi (Gitea) zu senden. + * **Source Control** Icon (Gabel-Symbol) -> Nachricht eingeben -> **Commit**. + * **Publish Branch** (oder "Sync Changes"), um den Branch zum Raspberry Pi (Gitea) zu senden. --- ### Phase 2: Testen (Beelink / `mindnet_dev`) -Hier prüfst du, ob dein neuer Code auf dem echten Server läuft, ohne die Produktion zu stören. +Hier prüfst du, ob dein neuer Code auf dem echten Server läuft. 1. **Einloggen:** `ssh user@` @@ -60,34 +57,34 @@ Hier prüfst du, ob dein neuer Code auf dem echten Server läuft, ohne die Produ 3. **Code holen:** ```bash git fetch + # Tipp: 'git branch -r' zeigt alle verfügbaren Branches an git checkout feature/wp04b-explanation git pull ``` -4. **Umgebung aktivieren (Venv):** - Damit Python die installierten Bibliotheken findet, musst du das Virtual Environment aktivieren: +4. **Umgebung vorbereiten:** ```bash source .venv/bin/activate + pip install -r requirements.txt # Nur nötig bei neuen Paketen ``` - *(Dein Prompt sollte jetzt `(.venv) user@...` zeigen)* -5. **Abhängigkeiten prüfen:** - *(Nur nötig, wenn du neue Libraries in `requirements.txt` eingetragen hast)* +5. **Test-Server neustarten (WICHTIG):** + Falls noch ein alter Prozess läuft, musst du ihn beenden, damit der neue Code geladen wird. + * Drücke `Strg + C` falls der Server noch im Vordergrund läuft. + * Oder nutze `pkill -f "uvicorn app.main:app"` um Hintergrunde-Prozesse zu stoppen. + + Starten auf **Port 8002**: ```bash - pip install -r requirements.txt + uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env ``` -6. **Test-Server starten:** - **WICHTIG:** Nutze Port **8002** und das Dev-Prefix! - Stelle sicher, dass in `~/mindnet_dev/.env` steht: `COLLECTION_PREFIX="mindnet_dev"`. - +6. **Validieren:** + Führe deine Tests in einem **zweiten Terminal** aus: ```bash - uvicorn app.main:app --host 0.0.0.0 --port 8002 + # Beispiel für Smoke-Test gegen Dev-Port + python3 tests/test_explanation_smoke.py --url http://localhost:8002/query ``` -7. **Testen:** - Prüfe deine Änderung (z.B. Browser auf `http://:8002/docs` oder Smoke-Test Skript). - --- ### Phase 3: Release (Gitea / Raspberry Pi) @@ -95,9 +92,8 @@ Hier prüfst du, ob dein neuer Code auf dem echten Server läuft, ohne die Produ Wenn der Test auf Port 8002 erfolgreich war: 1. Öffne Gitea im Browser. -2. Du solltest einen Hinweis sehen "feature/... had recent pushes". -3. Erstelle einen **Pull Request** (Dein Branch -> `main`). -4. **Merge** den Pull Request. +2. Erstelle einen **Pull Request** (Dein Branch -> `main`). +3. **Merge** den Pull Request. --- @@ -117,6 +113,24 @@ Jetzt bringen wir die Änderung in das Live-System (Port 8001). --- +### Phase 5: Aufräumen (Optional aber empfohlen) + +Damit das Chaos nicht wächst, löschen wir den fertigen Branch. + +1. **Gitea:** Im Pull Request auf "Delete Branch" klicken. +2. **Beelink (Dev):** + ```bash + cd ~/mindnet_dev + git checkout main + git pull + git branch -d feature/wp04b-explanation + ``` +3. **VS Code:** + * Auf `main` wechseln. + * `F1` -> `Git: Delete Branch` -> Branch auswählen. + +--- + ## 3. Cheat Sheet: Die wichtigsten Befehle | Wo? | Befehl | Was tut es? | @@ -125,16 +139,16 @@ Jetzt bringen wir die Änderung in das Live-System (Port 8001). | **VS Code** | `Sync Changes` | Lädt Code zu Gitea hoch. | | **Beelink** | `cd ~/mindnet_dev` | Gehe in den Test-Ordner. | | **Beelink** | `source .venv/bin/activate` | **Aktiviert Python-Umgebung.** | -| **Beelink** | `git fetch` | "Gibt es neue Branches auf Gitea?" | +| **Beelink** | `git fetch` | Aktualisiert die Liste der Remote-Branches. | +| **Beelink** | `git branch -r` | Zeigt alle Branches auf dem Server an. | | **Beelink** | `git checkout ` | Wechsle auf einen anderen Branch. | -| **Beelink** | `git pull` | Hol den neuesten Stand des aktuellen Branches. | | **Beelink** | `uvicorn ... --port 8002` | Startet Test-Server (Dev). | --- ## 4. Sicherheitsregeln -1. **Niemals** in `~/mindnet` (Prod-Ordner) experimentieren oder `git checkout` machen. Dieser Ordner bleibt immer auf `main`. +1. **Niemals** in `~/mindnet` (Prod-Ordner) experimentieren. Dieser Ordner bleibt immer auf `main`. 2. **Niemals** beide Umgebungen auf denselben `COLLECTION_PREFIX` zeigen lassen. * Prod `.env`: `COLLECTION_PREFIX="mindnet"` * Dev `.env`: `COLLECTION_PREFIX="mindnet_dev"`