From ecea8a0c22cdecaf86597da16598f0ecba0ec67e Mon Sep 17 00:00:00 2001 From: Tobi G Date: Sat, 5 Sep 2026 13:33:28 +0200 Subject: [PATCH] Neustart-Erkennung dokumentiert (AGENTS.md CZ) Co-Authored-By: Claude Opus 5 --- AGENTS.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index a2a647e..e16fa0e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11902,3 +11902,73 @@ Wert sofort in `fahrzeugprofil.json`. Dasselbe Muster wie beim Koordinatenfehler in Abschnitt CS: **ein fehlgeschlagener synthetischer Test ist kein Fehlerbeweis.** Erst mit echten Ereignissen pruefen, dann urteilen. + +## CZ. Nicht jedes Update braucht einen Neustart (2026.9.5.24) + +Frage des Eigentuemers: *"warum brauchen unsere updates immer einen HA reboot? +kannst du das nicht anders loesen?"* - Teils ja. + +### Zwei Faelle, nur einer ist unvermeidlich + +**Python-Code: Neustart noetig.** Home Assistant importiert die Module der +Integration einmal in seinen laufenden Prozess; daran haengen dann Entitaeten, +Zeittakte, Horcher, der Koordinator. Eine ausgetauschte `.py` auf der Platte +aendert daran nichts. `importlib.reload()` ueber alle Module waere technisch +moeglich, liesse aber alte Objekte referenziert und ergaebe eine Mischung aus +altem und neuem Code. Auch HACS verlangt deshalb einen Neustart. Bleibt so. + +**Oberflaechendateien: Neustart war unnoetig.** `frontend/` wird direkt von der +Platte ausgeliefert - `StaticPathConfig(STATIK_URL, ordner, False)`, also ohne +lange Cache-Vorgabe. Eine ersetzte `.js` ist sofort wirksam, es braucht nur ein +Neuladen im Browser. Gebunden war das nur an unseren eigenen Cache-Brecher +`?v={version}`, und der kam aus `async_get_integration()` - das liest aus +`hass.data[DATA_INTEGRATIONS]` und haelt das Manifest fuer die Laufzeit fest. + +### Die Unterscheidung ist bewusst schief + +`aktualisierung.neustart_noetig(alt, neu)` vergleicht beide Ordner ueber sha256 +je Datei (ohne `__pycache__`) und meldet **"kein Neustart" nur, wenn JEDE +Abweichung** unter `frontend/` liegt oder die `manifest.json` ist. Alles +andere - `.py`, `services.yaml`, `translations/`, `vorlage/` - gilt als +neustartpflichtig, auch wo es das im Einzelfall nicht waere. + +Der Grund fuer die Schieflage: ein faelschlich ausgelassener Neustart laesst +neuen Python-Code nie anlaufen, und der Fehler wird an ganz anderer Stelle +gesucht. Ein ueberfluessiger Neustart kostet eine Minute. + +`manifest.json` ist ausgenommen, weil sich ihre Versionsnummer bei **jeder** +Veroeffentlichung aendert - ohne die Ausnahme waere jedes Update ein +Neustart-Update und die Unterscheidung wertlos. Weil HA das Manifest +zwischenspeichert, liest `version_von_platte()` die Nummer direkt von der +Platte, und `koordinator.version_neu_lesen()` zieht sie nach einem +neustartfreien Update nach - sonst zeigten Panel und App weiter die alte +Fassung, und niemand wuesste, ob das Update angekommen ist. + +Panel und App zeigen dann "Seite neu laden" statt "Installation abschliessen - +Jetzt neu starten". + +### Bekannte Schwaeche: Zeilenenden + +Verglichen werden Datei-Inhalte. Steht die installierte Fassung mit CRLF auf +der Platte (Windows-Checkout, install.ps1) und kommt die neue aus dem +Gitea-Archiv mit LF, unterscheiden sich **alle** Dateien - auch die +`.py`-Dateien, deren Inhalt sachlich gleich ist. Das erste Update nach dieser +Aenderung meldet deshalb moeglicherweise "Neustart noetig", obwohl nur die +Oberflaeche gewechselt hat. Ab dem zweiten Update stammen beide Seiten aus dem +Archiv und der Vergleich stimmt. Bewusst nicht wegnormalisiert: die +Fehlerrichtung ist die sichere. + +### Stand der Pruefung + +Neun neue Testfaelle in `tests/aktualisierung/test_aktualisierung.py` decken +die Unterscheidung ab (nur frontend, nur manifest, geaenderte/neue/entfallene +`.py`, services.yaml, `__pycache__`, unlesbarer Ordner) - 23 Tests der Suite +gruen. + +**Der Durchlauf ueber den echten Gitea-Weg steht noch aus.** Er braucht eine +angemeldete Sitzung, und die war nach einem Browser-Neustart weg; ich melde +mich nicht selbst an. Vorbereitet ist er: Gitea steht auf **2026.9.5.24** mit +einer reinen Kommentaraenderung in `audi-dashboard-app.js` plus Versionsnummer, +die Testinstanz auf **2026.9.5.23**. Ein "Update installieren" dort muss +"nur Oberflaechendateien, kein Neustart noetig" melden. Die Probeaenderung +gehoert danach wieder heraus.