# Gitea Workflow - Best Practices

Diese Anleitung beschreibt den empfohlenen Git-Workflow für das PointCab Webexport Projekt.

## 🏗️ Repository erstellen

### In Gitea

1. **Anmelden** auf Ihrem Gitea-Server
2. **"+" → "Neues Repository"**
3. **Einstellungen:**
   - Name: `pointcab-webexport`
   - Beschreibung: `PointCab Webexport Server - Webbasiertes Sharing-System`
   - Sichtbarkeit: Privat (oder Öffentlich)
   - README initialisieren: Nein (wir haben bereits eine)
   - .gitignore: Keine (wir haben bereits eine)
   - Lizenz: MIT

### Lokales Repository verbinden

```bash
cd /home/ubuntu/pointcab_webexport_git

# Git initialisieren
git init

# Remote hinzufügen
git remote add origin https://ihr-gitea-server/username/pointcab-webexport.git

# Ersten Commit erstellen
git add .
git commit -m "Initial commit: PointCab Webexport Server"

# Auf Gitea pushen
git push -u origin main
```

## 🌿 Branch-Strategie

### Haupt-Branches

| Branch | Zweck | Schutz |
|--------|-------|--------|
| `main` | Produktions-Code | Geschützt |
| `develop` | Entwicklung | Optional geschützt |

### Feature-Branches

```
feature/neue-funktion
feature/upload-verbesserung
feature/multi-html-support
```

### Bugfix-Branches

```
bugfix/404-fehler
bugfix/passwort-problem
hotfix/kritischer-fehler
```

### Branch-Workflow

```
main ─────────────────────────────────────────►
       ↑                           ↑
       │                           │
develop ──●────●─────●────────●────►
          │    ↑     │        ↑
          │    │     │        │
feature/a ─●───┘     │        │
                     │        │
feature/b ───────────●────────┘
```

## 📝 Commit-Konventionen

### Format

```
<typ>(<bereich>): <kurze beschreibung>

<optionale längere beschreibung>

<optionale referenzen>
```

### Typen

| Typ | Beschreibung |
|-----|--------------|
| `feat` | Neue Funktion |
| `fix` | Bugfix |
| `docs` | Dokumentation |
| `style` | Formatierung |
| `refactor` | Code-Verbesserung |
| `test` | Tests |
| `chore` | Wartung |

### Beispiele

```bash
# Neue Funktion
git commit -m "feat(upload): Multi-HTML-Datei-Auswahl hinzugefügt"

# Bugfix
git commit -m "fix(assets): 404-Fehler bei Subfolder-Assets behoben"

# Dokumentation
git commit -m "docs: Installationsanleitung aktualisiert"

# Refactoring
git commit -m "refactor(service): Asset-Pfad-Auflösung verbessert"
```

## 🔀 Pull Requests

### PR erstellen

1. **Branch erstellen:**
   ```bash
   git checkout develop
   git pull
   git checkout -b feature/neue-funktion
   ```

2. **Änderungen machen:**
   ```bash
   # Code ändern...
   git add .
   git commit -m "feat: Neue Funktion implementiert"
   ```

3. **Branch pushen:**
   ```bash
   git push -u origin feature/neue-funktion
   ```

4. **PR in Gitea erstellen:**
   - Ziel-Branch: `develop` (oder `main` für Hotfixes)
   - Beschreibung mit Änderungen
   - Reviewer zuweisen (falls vorhanden)

### PR-Checkliste

- [ ] Code getestet
- [ ] Dokumentation aktualisiert
- [ ] Keine Secrets im Code
- [ ] Commit-Messages korrekt
- [ ] Ziel-Branch korrekt

### PR mergen

1. **Review (falls vorhanden)**
2. **Merge in Gitea:**
   - "Squash and Merge" für saubere Historie
   - Oder "Merge Commit" für vollständige Historie
3. **Branch löschen** (optional)

## 🏷️ Releases

### Versionierung (Semantic Versioning)

```
MAJOR.MINOR.PATCH

1.0.0 → 1.0.1 (Bugfix)
1.0.1 → 1.1.0 (Neue Funktion)
1.1.0 → 2.0.0 (Breaking Change)
```

### Release erstellen

1. **Version aktualisieren:**
   ```bash
   # package.json Version ändern
   npm version patch  # oder minor/major
   ```

2. **Changelog aktualisieren:**
   ```bash
   # docs/CHANGELOG.md bearbeiten
   ```

3. **Tag erstellen:**
   ```bash
   git tag -a v1.0.0 -m "Release v1.0.0"
   git push origin v1.0.0
   ```

4. **In Gitea:**
   - Releases → Neues Release
   - Tag auswählen: `v1.0.0`
   - Beschreibung mit Änderungen

### Release-Notes Template

```markdown
## v1.0.0 (2026-01-16)

### Neue Funktionen
- Multi-HTML-Datei-Unterstützung
- RAR-Entpacken auf dem Server

### Bugfixes
- 404-Fehler bei Subfolder-Assets behoben
- Passwort-Speicherung korrigiert

### Verbesserungen
- Performance-Optimierung beim Upload
- Bessere Fehlermeldungen

### Breaking Changes
- Keine
```

## 🔄 Typischer Workflow

### Neue Funktion entwickeln

```bash
# 1. Develop aktualisieren
git checkout develop
git pull

# 2. Feature-Branch erstellen
git checkout -b feature/neue-funktion

# 3. Entwickeln und committen
# ... code ändern ...
git add .
git commit -m "feat: Neue Funktion - Teil 1"

# ... weiter entwickeln ...
git add .
git commit -m "feat: Neue Funktion - Teil 2"

# 4. Branch pushen
git push -u origin feature/neue-funktion

# 5. PR in Gitea erstellen

# 6. Nach Merge: Branch löschen
git checkout develop
git pull
git branch -d feature/neue-funktion
```

### Bugfix (normal)

```bash
git checkout develop
git pull
git checkout -b bugfix/problem-beschreibung

# Fix implementieren
git add .
git commit -m "fix: Problem beschreibung behoben"
git push -u origin bugfix/problem-beschreibung

# PR erstellen → develop
```

### Hotfix (kritisch)

```bash
git checkout main
git pull
git checkout -b hotfix/kritischer-fehler

# Fix implementieren
git add .
git commit -m "fix: Kritischer Fehler behoben"
git push -u origin hotfix/kritischer-fehler

# PR erstellen → main (und develop!)
```

## ⚙️ CI/CD (Optional)

### Gitea Actions (falls verfügbar)

Erstellen Sie `.gitea/workflows/ci.yml`:

```yaml
name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: |
          cd nodejs_space
          npm install
      
      - name: Build
        run: |
          cd nodejs_space
          npm run build
      
      - name: Lint (optional)
        run: |
          cd nodejs_space
          npm run lint
```

### Manuelles Deployment

Nach erfolgreichem Merge in `main`:

```bash
# Auf dem Server
cd /var/www/pointcab_webexport_server
git pull origin main
cd nodejs_space
npm install
npm run build
pm2 restart pointcab-server
```

## 📋 Best Practices Zusammenfassung

1. **Niemals direkt auf `main` pushen**
2. **Immer über Pull Requests arbeiten**
3. **Aussagekräftige Commit-Messages**
4. **Regelmäßig `develop` aktualisieren**
5. **Feature-Branches klein halten**
6. **Branches nach Merge löschen**
7. **Tags für Releases verwenden**
8. **Changelog pflegen**

## 🔗 Nützliche Git-Befehle

```bash
# Status
git status
git log --oneline -10

# Branches
git branch -a
git checkout -b neuer-branch

# Remote
git remote -v
git fetch --all

# Stash (temporär speichern)
git stash
git stash pop

# Rebase (Historie aufräumen)
git rebase -i HEAD~3

# Diff
git diff
git diff develop
```

---

**Weitere Dokumentation:** [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)