Drift Dependency Update

Workflow für alle Änderungen an pyproject.toml-Abhängigkeiten im Drift-Repo. Deckt: neue Abhängigkeit hinzufügen, bestehende upgraden/einschränken, Abhängigkeit entfernen.

KRITISCH: pyproject.toml und uv.lock sind unlösbar gekoppelt. Beide Dateien müssen im selben Commit landen. Das Pre-Push-Gate 5 blockiert jeden Push, bei dem pyproject.toml geändert, uv.lock aber nicht committet wurde.

Wann verwenden

• pyproject.toml-Abhängigkeit soll geändert, hinzugefügt oder entfernt werden
• uv.lock soll mit aktuellen Constraints synchronisiert werden
• Security-Patch für eine direkte oder transitive Abhängigkeit
• CI schlägt fehl mit „Lockfile not synchronized" oder ähnlichem

Technischer Kontext

Dependency-Gruppen in [project.optional-dependencies]:

Lokale Venv-Aktivierung (Windows):

.\.venv\Scripts\Activate.ps1

Wichtige uv-Befehle:

Schritt-für-Schritt-Workflow

Schritt 0 — Policy Gate

### Drift Policy Gate
- Trivialtask: JA
- Zulässig: JA → rein mechanisch, ohne Verhaltens-, Policy-, Architektur- oder Signaleffekt

Dependency-Updates sind chore:-Commits. Sie lösen kein feat:/fix:-Gate aus und erfordern kein CHANGELOG-Update. Ausnahme: Ein Upgrade behebt einen produktiven Bug → dann fix:.

Schritt 1 — Abhängigkeit klassifizieren

Vor der Änderung klären:

• Nur pyproject.toml (Versions-Constraint ändern): direkt editieren → dann uv lock.
• Neue Abhängigkeit hinzufügen: uv add <paket> bevorzugen — schreibt pyproject.toml und uv.lock atomar.
• Security-Patch für transitive Abhängigkeit (nicht in pyproject.toml): uv lock --upgrade-package <paket> + kein pyproject.toml-Edit nötig.
• Abhängigkeit entfernen: uv remove <paket>.

Schritt 2 — Lockfile synchronisieren

Nach jedem manuellen Edit von pyproject.toml:

uv lock

Prüfen, ob keine Konflikte ausgegeben werden. Bei Konflikten Constraint in pyproject.toml anpassen und erneut ausführen.

Schritt 3 — Devenv aktualisieren

uv sync --all-extras

Stellt sicher, dass das lokale Venv die neuen Versionen enthält, bevor Tests laufen.

Schritt 4 — Typecheck

.\.venv\Scripts\python.exe -m mypy src/drift --ignore-missing-imports

Schlägt der Typecheck durch inkompatible API-Änderungen fehl, Constraint in pyproject.toml einschränken oder Typ-Fehler beheben.

Schritt 5 — Quick-Tests

.\.venv\Scripts\python.exe -m pytest tests/ --ignore=tests/test_smoke_real_repos.py -m "not slow" -q -n auto --dist=loadscope

Bei Testfehlern durch API-Änderungen der aktualisierten Bibliothek:

1. Prüfen, ob es einen Workaround im Drift-Code gibt.
2. Constraint ggf. zurücksetzen (<neue_version).
3. Issue gegen die Bibliothek vorbereiten, falls es ein echter Bug ist.

Schritt 6 — Beide Artefakte committen

PFLICHT: pyproject.toml und uv.lock immer gemeinsam in einem Commit.

git add pyproject.toml uv.lock
git status --short   # Sicherheitscheck: keine unerwünschten Dateien
git commit -m "chore: update <paket> to <version>"

Commit-Typ-Regeln:

Schritt 7 — Pre-Push-Gate-Check (vor dem Push)

Gate 4 (Version Bump) feuert, wenn pyproject.toml geändert wurde:

• PSR bumpt die Version nicht für chore:-Commits → Gate würde blockieren.
• Lösung für chore:-nur-Dependency-Pushes:

DRIFT_SKIP_VERSION_BUMP=1 git push

Bei fix: oder feat:-Commits ist kein Bypass nötig — PSR erstellt einen Version-Bump-Commit in CI.

Häufige Fehler (und Korrekturen)

Checkliste (Kurzform)

[ ] Art der Änderung klassifiziert (add / upgrade / remove / security-patch)
[ ] pyproject.toml bearbeitet (oder uv add/remove genutzt)
[ ] uv lock ausgeführt — keine Konflikte
[ ] uv sync --all-extras ausgeführt
[ ] mypy src/drift — sauber
[ ] pytest quick suite — grün
[ ] git add pyproject.toml uv.lock (beide!)
[ ] Commit-Typ korrekt (chore: / fix: / feat:)
[ ] DRIFT_SKIP_VERSION_BUMP=1 wenn chore:-Push