Document upstream upgrade and rollback workflow

docs/UPGRADE_INFO.md

@@ -0,0 +1,150 @@
+# Upgrade-Info: Neue LTX-Desktop-Versionen übernehmen
+
+Diese Anleitung beschreibt den vorgesehenen Wartungsablauf für LTX DeskWEB.
+Sie ist kein automatischer Updater und erteilt keine Freigabe, produktive Dienste
+oder GPU-Modi umzuschalten. Stand: 29. September 2026.
+
+## Ausgangslage und Ziel
+
+LTX DeskWEB verwendet die Oberfläche von LTX Athena / LTX Desktop und ergänzt
+Browser-Dateizugriff, Anmeldung und HTTP-Weiterleitung. Die Generierung läuft
+weiterhin im separat verwalteten LTX-Backend auf Athena.
+
+Der erste Import war ein **Quellcode-Snapshot**, kein Fork mit vollständig
+übernommener Upstream-Git-Historie. Grundlage und mitübernommene lokale Änderungen
+stehen in [PROVENANCE.md](PROVENANCE.md). Daher ist ein einfaches `git pull` vom
+Originalprojekt derzeit kein geeigneter Update-Weg. Eine automatisierte
+Upstream-Synchronisierung ist noch nicht eingerichtet.
+
+GUI und Backend haben getrennte Versionsstände. Neue Funktionen können Änderungen
+an beiden benötigen. Es wird deshalb immer eine **geprüfte Kombination** aus
+Web-GUI, LTX-Backend und gegebenenfalls Modellversion veröffentlicht. Eine neue
+GUI-Schaltfläche macht eine vom Backend oder Modell nicht unterstützte Funktion
+nicht verfügbar. Keine automatischen Produktivupdates auf `latest`.
+
+## 1. Update prüfen und Vergleichsbasis herstellen
+
+- Release Notes, Änderungen an API/Schema, Projektformat, Abhängigkeiten und
+  Lizenzen im [Originalrepository](https://github.com/Lightricks/LTX-Desktop)
+  prüfen. Gewünschten Release-Tag und vollständigen Commit festhalten.
+- Änderungen nach Oberfläche, Electron/Dateifunktionen und Backend einordnen.
+  Ermitteln, welche neuen Funktionen unsere vorhandene Backend-Version unterstützt.
+- Vor dem ersten größeren Update die ursprüngliche Git-Historie in einem
+  **separaten Referenz-Checkout** bereitstellen. Den in PROVENANCE.md genannten
+  Basis-Commit dort verifizieren und die mitimportierten LTX-Athena-Anpassungen
+  gesondert erfassen. Der lokale Athena-Commit muss nicht im offiziellen
+  Repository existieren; fehlende Herkunft zuerst klären, nicht erraten.
+- Den ursprünglichen Snapshot und unsere Browser-Änderungen als nachvollziehbare
+  Vergleichsbasis dokumentieren. Keine erzwungene Zusammenführung unabhängiger
+  Historien und kein Überschreiben der vorhandenen Dateien mit dem neuesten Stand.
+
+## 2. Isoliert übernehmen
+
+Einen Arbeitsbranch wie `codex/ltx-upgrade-<version>` anlegen. Vorhandene lokale
+Änderungen erhalten. Noch keine Änderung an der laufenden Installation.
+
+Die relevanten Upstream-Änderungen gezielt übernehmen und Konflikte prüfen.
+Besonders wichtig sind:
+
+| Bereich | Was erhalten bzw. geprüft werden muss |
+| --- | --- |
+| `frontend/lib/web-platform.ts` | Browser-Uploads, Medienzugriff und Ersatz der Electron-Funktionen |
+| `frontend/App.tsx` | Browser-Anmeldung; keine lokale Python-/Modellinstallation |
+| `frontend/lib/backend.ts` und `api-client.ts` | Native LTX-API und zur Backend-Version passendes Schema |
+| `server/` | Zugangsdaten bleiben serverseitig; feste API-Zieladresse; Dateipfadgrenzen |
+| Projektablage / Projektschema | Bestehende Projekte lesbar; Migration und Rückweg geklärt |
+| Docker / Compose | Keine KI-Laufzeit, GPU-Geräte oder Docker-Socket in der GUI |
+
+Browser-Anpassungen möglichst in diesen wenigen Grenzen bündeln. Neue
+Electron-Aufrufe brauchen eine echte Browser-Implementierung oder einen klaren
+Hinweis, dass die Funktion noch nicht verfügbar ist. Keine simulierten Erfolge.
+API-Typen nur aus dem passenden Backend-Stand übernehmen beziehungsweise erzeugen;
+nicht unabhängig auf die neueste Version setzen.
+
+## 3. Prüfen und Testcontainer bauen
+
+Zunächst die lokalen Prüfungen ausführen:
+
+```sh
+npm ci
+npm run typecheck
+npm test
+npm run build
+```
+
+Danach ein Image mit eindeutiger Versionskennung bauen. Einen separaten
+Testcontainer mit **anderem Namen, freiem Port, eigener Browser-Origin und eigenen
+Testdateien** starten. Die laufende GUI bleibt erhalten. Keine bestehenden
+Produktivdaten für Migrationstests verändern; gesicherte Kopien verwenden.
+
+Achtung: Das Athena-Override enthält einen festen Container-Namen sowie Host-
+Networking. Nur einen anderen Compose-Projektnamen zu wählen reicht deshalb
+nicht. Auch `container_name`, der tatsächlich verwendete Server-`PORT` und
+`PUBLIC_ORIGIN` müssen im Test-Override angepasst werden. Bei Host-Networking
+bewirkt eine andere Portveröffentlichung allein nichts.
+
+Testreihenfolge:
+
+1. Synthetisches Backend und Testmedien für Anmeldung, Upload, Vorschau,
+   Downloads, Dateisicherheit und Fehlermeldungen verwenden.
+2. Projekte anlegen, bearbeiten, sichern, wiederherstellen und nach Neuladen
+   öffnen. Alte Projektkopien prüfen, bevor eine Migration freigegeben wird.
+3. Native API-Verträge einschließlich Fehlerantworten und Modellfähigkeiten
+   vergleichen. Nicht verfügbare Funktionen korrekt ausblenden oder erklären.
+4. Nach Freigabe eines geeigneten GPU-Testfensters mit dem echten LTX-Backend
+   Generierung, Fortschritt, Abbruch, Ergebnisübernahme und Wiederverbindung testen.
+   Die alte GUI darf dabei weiter laufen; beide GUIs teilen aber dasselbe Backend
+   und damit dessen Jobs/GPU-Zustand. Ein zweiter GUI-Container isoliert keine
+   Generierung. Keine parallelen konkurrierenden Testaufträge starten.
+5. Die neu übernommenen Funktionen gezielt testen, z. B. Bild-/Audioeingabe,
+   Extend, Retake oder LoRA — jeweils nur, soweit das konkrete Modell sie unterstützt.
+
+Ein erfolgreicher Frontend-Build oder synthetischer Test ersetzt keinen echten
+Backend-Integrationstest. Nicht geprüfte Funktionen ausdrücklich dokumentieren.
+
+## 4. Release vorbereiten und ausrollen
+
+Vor der Umstellung festhalten:
+
+- Web-GUI-Commit, Version und Image-Digest.
+- Übernommener Upstream-Release/Commit sowie LTX-Backend-Version und Image-Digest.
+- Geprüfte Modellversionen, neue Funktionen, Einschränkungen und Testergebnisse.
+- Änderungen an Konfiguration, API und Projektformat.
+- Vorheriger funktionierender Stand und konkreter Rückfallweg.
+
+Projekte vor einer Formatänderung sichern. Die erste Web-Version speichert sie im
+Browser: Das Sichern nur des Containers genügt nicht. JSON-Backup und zugehörige
+Medien getrennt erhalten; das JSON enthält keine Mediendateien. Konfiguration und
+Secrets geschützt außerhalb von Git sichern, ohne sie auszugeben.
+
+Erst nach erfolgreichen Prüfungen den GUI-Container gezielt ersetzen. Eine nötige
+Backend-Aktualisierung gesondert planen; laufende Generierungen vorher beenden
+lassen oder einen Abbruch ausdrücklich abstimmen. Andere Athena-Dienste bleiben
+unverändert. GUI-Update und Backend-Update sind keine pauschale Freigabe für
+Treiber-, Netzwerk-, WireGuard- oder Hoständerungen.
+
+Nach dem Rollout Erreichbarkeit, Anmeldung, Deck-Dienstliste und native
+API-Verbindung prüfen. Den alten Image-Stand bis zum Abschluss der Abnahme
+behalten. Betriebsbefehle: [ATHENA_DEPLOYMENT.md](ATHENA_DEPLOYMENT.md).
+
+## 5. Rückfall
+
+Bei Problemen die vorherige GUI-Version mit ihrer bekannten Konfiguration starten.
+Wurde auch das Backend verändert, die zuvor geprüfte Kombination wiederherstellen.
+Keine Modellgewichte oder Nutzerdaten beim Rückwechsel löschen.
+
+Ein Image-Rollback macht eine Datenmigration nicht rückgängig. Hat die neue Version
+Projekte inkompatibel verändert, vorher sichern und die passenden Projektkopien
+wiederherstellen. Deshalb Migrationen zuerst an Kopien prüfen und Backups nicht
+mit migrierten Daten überschreiben.
+
+## Noch vorzubereiten
+
+- Verifizierte Upstream-Vergleichsbasis einschließlich der lokalen Athena-Patches.
+- Wiederholbarer Testcontainer-Workflow mit isolierten Daten und Ports.
+- Dokumentierte Kompatibilitätsmatrix GUI ↔ Backend ↔ Modell.
+- Erweiterte Integrationstests für lang laufende Jobs und Projektmigrationen.
+
+Diese Punkte sind geplant; diese Datei behauptet nicht, dass sie bereits
+implementiert sind. Nach jedem Upgrade PROVENANCE.md, VALIDATION.md und die
+Kompatibilitätsangaben aktualisieren.