Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
d0ecc5316f
mindnet/docs/dev_workflow.md

4.8 KiB
Raw Blame History

Mindnet v2.2 – Entwickler-Workflow

Datei: DEV_WORKFLOW.md Stand: 2025-12-07 (Aktualisiert: Sync-First Strategie)

Dieses Handbuch beschreibt den Entwicklungszyklus zwischen Windows PC (IDE), Raspberry Pi (Gitea) und Beelink (Runtime/Server).

1. Die Architektur

  • Windows 11 (VS Code): Hier schreibst du Code. Nie direkt auf main arbeiten!
  • Raspberry Pi (Gitea): Der Tresor. Speichert den Code und verwaltet Versionen.
  • Beelink (Runtime): Hier läuft die Software. Wir trennen strikt:
    • PROD (~/mindnet): Läuft stabil auf main. Port 8001.
    • DEV (~/mindnet_dev): Deine Spielwiese für Branches. Port 8002.

2. Der Zyklus: Von der Idee zum Release

Phase 1: Entwicklung (Windows / VS Code)

Hier erstellst du die neue Funktion in einer sicheren Umgebung.

  1. Basis aktualisieren (WICHTIG!): Bevor du startest, muss dein lokales main auf dem Stand des Servers sein.

    • Klicke unten links auf den aktuellen Branch und wähle main.
    • Klicke links im Menü "Source Control" auf die drei Punkte (...) -> Pull (oder das Synchronisieren-Symbol).
    • Erst jetzt hast du alle Dateien!

  2. Branch erstellen:

    • Klicke wieder unten links auf main.
    • Wähle + Create new branch....
    • Gib den Namen ein: feature/was-ich-tue (z.B. feature/wp04b-explanation).
    • Drücke Enter.

  3. Sicherheits-Check:

    • Steht unten links jetzt dein Feature-Branch? Nur dann darfst du Code ändern!

  4. Coden:

    • Nimm deine Änderungen vor.

  5. Sichern & Hochladen:

    • 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.

  1. Einloggen: ssh user@<BEELINK-IP>

  2. In die Werkstatt gehen: cd /home/llmadmin/mindnet_dev

  3. Code holen:

    git fetch
# Tipp: 'git branch -r' zeigt alle verfügbaren Branches an
git checkout feature/wp04b-explanation
git pull

  4. Umgebung vorbereiten:

    source .venv/bin/activate
pip install -r requirements.txt  # Nur nötig bei neuen Paketen

  5. Test-Server neustarten (WICHTIG): Falls noch ein alter Prozess läuft, musst du ihn beenden.

    • Drücke Strg + C falls der Server noch im Vordergrund läuft.
    • Oder nutze pkill -f "uvicorn app.main:app".

    Starten auf Port 8002:

    uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env

  6. Validieren: Führe deine Tests in einem zweiten Terminal aus:

    # Beispiel für Smoke-Test gegen Dev-Port
python3 tests/test_explanation_smoke.py --url http://localhost:8002/query

Phase 3: Release (Gitea / Raspberry Pi)

Wenn der Test auf Port 8002 erfolgreich war:

  1. Öffne Gitea im Browser.
  2. Erstelle einen Pull Request (Dein Branch -> main).
  3. Merge den Pull Request.

Phase 4: Deployment (Beelink / mindnet)

Jetzt bringen wir die Änderung in das Live-System (Port 8001).

  1. Deploy-Agent (Automatisch): Wenn dein deploy.yml aktiv ist, passiert das jetzt von selbst!

  2. Manuell (Falls nötig):

    cd /home/llmadmin/mindnet
git pull origin main
sudo systemctl restart mindnet-api

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): 
    cd ~/mindnet_dev
git checkout main
git pull
git branch -d feature/wp04b-explanation
  3. VS Code:
    • Auf main wechseln.
    • Sync drücken (um Löschung vom Server zu erfahren).
    • F1 -> Git: Delete Branch -> Branch auswählen.

3. Cheat Sheet: Die wichtigsten Befehle

Wo? Befehl Was tut es?
VS Code Sync (auf main) WICHTIG: Holt neuesten Code vom Server.
VS Code Klick auf Branch Branch erstellen oder wechseln.
Beelink source .venv/bin/activate Aktiviert Python-Umgebung.
Beelink git fetch Aktualisiert Remote-Branches.
Beelink git checkout <name> Wechsle Branch.
Beelink git pull Aktualisiere aktuellen Branch.
Beelink uvicorn ... --port 8002 Startet Test-Server (Dev).

4. Troubleshooting

"Hilfe, in meinem neuen Branch fehlen Dateien!" Das passiert, wenn du beim Erstellen nicht aktuell warst.

  • Lösung: 
    # In VS Code Terminal:
git checkout feature/mein-kaputter-branch
git merge main
# (Das holt die fehlenden Dateien aus main nach)