Compare commits
2
Commits
V2.2.1
...
78d8ab11ed
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
78d8ab11ed | ||
|
|
d49da1b5fe |
+62
-45
@@ -1,6 +1,6 @@
|
|||||||
# Mindnet v2.2 – Entwickler-Workflow
|
# Mindnet v2.2 – Entwickler-Workflow
|
||||||
**Datei:** `DEV_WORKFLOW.md`
|
**Datei:** `DEV_WORKFLOW.md`
|
||||||
**Stand:** 2025-12-07
|
**Stand:** 2025-12-07 (Aktualisiert: Sync-First Strategie)
|
||||||
|
|
||||||
Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server).
|
Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server).
|
||||||
|
|
||||||
@@ -22,34 +22,33 @@ Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE),
|
|||||||
|
|
||||||
Hier erstellst du die neue Funktion in einer sicheren Umgebung.
|
Hier erstellst du die neue Funktion in einer sicheren Umgebung.
|
||||||
|
|
||||||
1. **Sicherstellen, dass Git bereit ist:**
|
1. **Basis aktualisieren (WICHTIG!):**
|
||||||
* Öffne VS Code.
|
Bevor du startest, muss dein lokales `main` auf dem Stand des Servers sein.
|
||||||
* Unten links in der blauen Leiste sollte der aktuelle Branch stehen (z.B. `main`).
|
* 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 (WICHTIG):**
|
2. **Branch erstellen:**
|
||||||
* Klicke unten links auf den Branch-Namen (z.B. `main`).
|
* Klicke wieder unten links auf `main`.
|
||||||
* Wähle im Menü oben `+ Create new branch...`.
|
* Wähle `+ Create new branch...`.
|
||||||
* Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp04b-explanation`).
|
* Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp04b-explanation`).
|
||||||
* Drücke **Enter**.
|
* Drücke **Enter**.
|
||||||
|
|
||||||
3. **Sicherheits-Check:**
|
3. **Sicherheits-Check:**
|
||||||
* Schau unten links: Steht dort jetzt `feature/wp04b-explanation`?
|
* Steht unten links jetzt dein Feature-Branch? **Nur dann darfst du Code ändern!**
|
||||||
* **Nur wenn dort dein Feature-Branch steht, darfst du Code ändern!** Alles, was du jetzt speicherst, landet in diesem Branch.
|
|
||||||
|
|
||||||
4. **Coden:**
|
4. **Coden:**
|
||||||
* Nimm deine Änderungen vor.
|
* Nimm deine Änderungen vor.
|
||||||
|
|
||||||
5. **Sichern & Hochladen:**
|
5. **Sichern & Hochladen:**
|
||||||
* Klicke links auf das **Source Control** Icon (Gabel-Symbol).
|
* **Source Control** Icon (Gabel-Symbol) -> Nachricht eingeben -> **Commit**.
|
||||||
* Gib eine Nachricht ein: "feat: Add explanation layer logic".
|
* **Publish Branch** (oder "Sync Changes"), um den Branch zum Raspberry Pi (Gitea) zu senden.
|
||||||
* Klicke auf **Commit**.
|
|
||||||
* Klicke auf **Publish Branch** (oder "Sync Changes"), um den Branch zum Raspberry Pi (Gitea) zu senden.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### Phase 2: Testen (Beelink / `mindnet_dev`)
|
### 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:**
|
1. **Einloggen:**
|
||||||
`ssh user@<BEELINK-IP>`
|
`ssh user@<BEELINK-IP>`
|
||||||
@@ -60,34 +59,34 @@ Hier prüfst du, ob dein neuer Code auf dem echten Server läuft, ohne die Produ
|
|||||||
3. **Code holen:**
|
3. **Code holen:**
|
||||||
```bash
|
```bash
|
||||||
git fetch
|
git fetch
|
||||||
|
# Tipp: 'git branch -r' zeigt alle verfügbaren Branches an
|
||||||
git checkout feature/wp04b-explanation
|
git checkout feature/wp04b-explanation
|
||||||
git pull
|
git pull
|
||||||
```
|
```
|
||||||
|
|
||||||
4. **Umgebung aktivieren (Venv):**
|
4. **Umgebung vorbereiten:**
|
||||||
Damit Python die installierten Bibliotheken findet, musst du das Virtual Environment aktivieren:
|
|
||||||
```bash
|
```bash
|
||||||
source .venv/bin/activate
|
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:**
|
5. **Test-Server neustarten (WICHTIG):**
|
||||||
*(Nur nötig, wenn du neue Libraries in `requirements.txt` eingetragen hast)*
|
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**:
|
||||||
```bash
|
```bash
|
||||||
pip install -r requirements.txt
|
uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env
|
||||||
```
|
```
|
||||||
|
|
||||||
6. **Test-Server starten:**
|
6. **Validieren:**
|
||||||
**WICHTIG:** Nutze Port **8002** und das Dev-Prefix!
|
Führe deine Tests in einem **zweiten Terminal** aus:
|
||||||
Stelle sicher, dass in `~/mindnet_dev/.env` steht: `COLLECTION_PREFIX="mindnet_dev"`.
|
|
||||||
|
|
||||||
```bash
|
```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://<BEELINK-IP>:8002/docs` oder Smoke-Test Skript).
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### Phase 3: Release (Gitea / Raspberry Pi)
|
### Phase 3: Release (Gitea / Raspberry Pi)
|
||||||
@@ -95,9 +94,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:
|
Wenn der Test auf Port 8002 erfolgreich war:
|
||||||
|
|
||||||
1. Öffne Gitea im Browser.
|
1. Öffne Gitea im Browser.
|
||||||
2. Du solltest einen Hinweis sehen "feature/... had recent pushes".
|
2. Erstelle einen **Pull Request** (Dein Branch -> `main`).
|
||||||
3. Erstelle einen **Pull Request** (Dein Branch -> `main`).
|
3. **Merge** den Pull Request.
|
||||||
4. **Merge** den Pull Request.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -117,27 +115,46 @@ 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.
|
||||||
|
* Sync drücken (um Löschung vom Server zu erfahren).
|
||||||
|
* `F1` -> `Git: Delete Branch` -> Branch auswählen.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 3. Cheat Sheet: Die wichtigsten Befehle
|
## 3. Cheat Sheet: Die wichtigsten Befehle
|
||||||
|
|
||||||
| Wo? | Befehl | Was tut es? |
|
| Wo? | Befehl | Was tut es? |
|
||||||
| :--- | :--- | :--- |
|
| :--- | :--- | :--- |
|
||||||
| **VS Code** | `Klick auf Branch-Namen` | Branch erstellen oder wechseln. |
|
| **VS Code** | `Sync (auf main)` | **WICHTIG:** Holt neuesten Code vom Server. |
|
||||||
| **VS Code** | `Sync Changes` | Lädt Code zu Gitea hoch. |
|
| **VS Code** | `Klick auf Branch` | Branch erstellen oder wechseln. |
|
||||||
| **Beelink** | `cd ~/mindnet_dev` | Gehe in den Test-Ordner. |
|
|
||||||
| **Beelink** | `source .venv/bin/activate` | **Aktiviert Python-Umgebung.** |
|
| **Beelink** | `source .venv/bin/activate` | **Aktiviert Python-Umgebung.** |
|
||||||
| **Beelink** | `git fetch` | "Gibt es neue Branches auf Gitea?" |
|
| **Beelink** | `git fetch` | Aktualisiert Remote-Branches. |
|
||||||
| **Beelink** | `git checkout <name>` | Wechsle auf einen anderen Branch. |
|
| **Beelink** | `git checkout <name>` | Wechsle Branch. |
|
||||||
| **Beelink** | `git pull` | Hol den neuesten Stand des aktuellen Branches. |
|
| **Beelink** | `git pull` | Aktualisiere aktuellen Branch. |
|
||||||
| **Beelink** | `uvicorn ... --port 8002` | Startet Test-Server (Dev). |
|
| **Beelink** | `uvicorn ... --port 8002` | Startet Test-Server (Dev). |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 4. Sicherheitsregeln
|
## 4. Troubleshooting
|
||||||
|
|
||||||
1. **Niemals** in `~/mindnet` (Prod-Ordner) experimentieren oder `git checkout` machen. Dieser Ordner bleibt immer auf `main`.
|
**"Hilfe, in meinem neuen Branch fehlen Dateien!"**
|
||||||
2. **Niemals** beide Umgebungen auf denselben `COLLECTION_PREFIX` zeigen lassen.
|
Das passiert, wenn du beim Erstellen nicht aktuell warst.
|
||||||
* Prod `.env`: `COLLECTION_PREFIX="mindnet"`
|
* **Lösung:**
|
||||||
* Dev `.env`: `COLLECTION_PREFIX="mindnet_dev"`
|
```bash
|
||||||
3. **Port-Disziplin:**
|
# In VS Code Terminal:
|
||||||
* **PROD:** Port 8001
|
git checkout feature/mein-kaputter-branch
|
||||||
* **DEV:** Port 8002
|
git merge main
|
||||||
|
# (Das holt die fehlenden Dateien aus main nach)
|
||||||
Reference in new issue
Block a user