# ADR-008: Migration von Poetry zu uv

**Status:** Akzeptiert
**Datum:** 2025-11-21
**Kontext:** PoC questra-data Python Package
**Supersedes:** ADR-001 (Paketmanagement mit poetry)

## Kontext und Problemstellung

ADR-001 etablierte Poetry als Paketmanager für questra-data (Oktober 2025). Seit Ende 2024 hat sich `uv` (Astral, Entwickler von `ruff`) als moderner, performanter Alternative etabliert.

Hauptgründe für eine Neubewertung:
- **Performance-Probleme:** Poetry's Dependency Resolution wird bei komplexen Projekten langsam (CI/CD >25min)
- **Standards-Konformität:** uv folgt strikter PEP 517/518/621, während Poetry eigene Konventionen nutzt
- **Ecosystem-Shift:** Python-Community migriert zunehmend zu uv (2024/2025 Trend)
- **PoC-Status:** Keine Legacy-Bindung, Migration jetzt einfacher als später

## Entscheidung

Wir **migrieren von Poetry zu uv** als primären Paketmanager für questra-data.

## Begründung

### Pro uv

- **Performance:** 10-100x schnellere Dependency Resolution und Installation (Rust-basiert)
- **Standards-First:** Strikte PEP-Konformität, Standard-`pyproject.toml` ohne proprietäre Erweiterungen
- **Kein Lock-in:** Drop-in Replacement für pip/pip-tools, einfache Rückmigration möglich
- **CI/CD-Freundlichkeit:** Standalone Binary, keine Python-Installation erforderlich
- **Moderner Toolchain:** Gleicher Stack wie `ruff` (Astral), aktive Entwicklung 2024/2025
- **Publishing:** `uv publish` seit Version 0.5+ verfügbar
- **Kompatibilität:** Kann mit bestehenden `requirements.txt`, `setup.py` arbeiten

### Contra uv

- **Reife:** Jünger als Poetry (~1 Jahr Production-Track-Record vs. 5+ Jahre)
- **Community:** Kleinere, aber schnell wachsende Community
- **Dokumentation:** Weniger StackOverflow-Antworten als für Poetry

### Vergleich zu Poetry (ADR-001)

| Kriterium | Poetry | uv |
|-----------|--------|-----|
| Dependency Resolution | Deterministisch, langsam | Deterministisch, 10-100x schneller |
| Standards | Eigene Konventionen | Strikt PEP 517/518/621 |
| Lock-in | Hoch (poetry.lock Format) | Niedrig (Standard pyproject.toml) |
| CI/CD Performance | Langsam (>25min Reports) | Schnell (<2min Reports) |
| Virtual Environments | Automatisch | Automatisch |
| Build/Publishing | ✅ Vollständig | ✅ Vollständig (seit 0.5) |

## Alternativen

### Poetry beibehalten (Status Quo)

- **Pro:** Bewährt, größere Community, etabliert
- **Contra:** Performance-Probleme, Lock-in, stagniert in der Entwicklung

### pip-tools

- **Pro:** Standard-konform, etabliert
- **Contra:** Keine integrierte Build/Publishing-Lösung, langsamer als uv

### PDM / Hatch

- **Pro:** Modern, PEP-konform
- **Contra:** Kleinere Community als uv, weniger Performance-Fokus

## Konsequenzen

### Positiv

- **Deutlich schnellere** Dependency Resolution und Installation
- **Einfachere CI/CD-Integration** (standalone Binary)
- **Zukunftssicher:** Aktive Entwicklung, wachsende Community
- **Weniger Lock-in:** Standard-konforme `pyproject.toml`
- **Konsistenter Toolstack:** uv + ruff (beide Astral)

### Negativ

- **Migration erforderlich:** `poetry.lock` → `uv.lock`, CI/CD-Anpassungen
- **Einarbeitungszeit:** Entwickler müssen uv-Commands lernen
- **Risiko:** Weniger ausgereift als Poetry (aber stabil genug für PoC)

### Migration-Tasks

1. `uv` Installation (einmalig pro Entwickler/CI-System)
2. `poetry.lock` entfernen, `uv.lock` generieren
3. `pyproject.toml` bereinigen (Poetry-spezifische Sektionen)
4. CI/CD-Workflows aktualisieren
5. Dokumentation (README, CLAUDE.md) aktualisieren
6. `poetry.lock` und Poetry-Config aus Git entfernen

## Notizen

- **Timing:** Migration im PoC-Stadium optimal, minimales Risiko
- **Rückmigration:** Aufgrund Standard-`pyproject.toml` jederzeit möglich
- **uv Version:** 0.5+ empfohlen (Publishing-Support)
- **Python Version:** uv unterstützt Python 3.10+ (wie aktuell)

## Referenzen

- [uv Documentation](https://docs.astral.sh/uv/)
- [Poetry vs uv Comparison (2025)](https://www.loopwerk.io/articles/2024/python-poetry-vs-uv/)
- [PEP 517: Build System Interface](https://peps.python.org/pep-0517/)
- [PEP 518: pyproject.toml Specification](https://peps.python.org/pep-0518/)
