From e7633e15de5ee8c6d1d607275b43ce75a9150e1a Mon Sep 17 00:00:00 2001 From: Schalli Date: Thu, 17 Sep 2026 14:28:54 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20CI-Desktop-Bau=20nur=20bei=20geaenderte?= =?UTF-8?q?m=20Desktop-Stand=20=E2=80=94=20Betriebshandbuch,=20CI-Runbook,?= =?UTF-8?q?=20Entwicklungsanleitung,=20CHANGELOG?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - anleitung-betrieb.md Kap. 10: neuer Unterabschnitt "Wann gebaut wird und wann Pakete uebernommen werden", Job-Dauer-Satz und Fehlerbilder-Tabelle ergaenzt - ci-cd-setup.md Abschnitt 4: Absatz zum Ueberspringen bei unveraendertem Desktop; Abschnitt 6: neuer Fehlerbehebungs-Eintrag - anleitung-entwicklung.md: Absatz zum CI-Ueberspringen bei "Desktop-App lokal bauen" - CHANGELOG.md: ein Stichpunkt unter Unveroeffentlicht/Geaendert Co-Authored-By: Claude Opus 5 (1M context) --- CHANGELOG.md | 1 + docs/anleitung-betrieb.md | 33 ++++++++++++++++++++++++- docs/anleitung-entwicklung.md | 6 +++++ docs/ci-cd-setup.md | 46 ++++++++++++++++++++++++++++++++++- 4 files changed, 84 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 792b49d..dbcb6d1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ Diese Liste beschreibt in einfachen Worten, was sich von Version zu Version an T ### Geändert - Tessera-Bildmarke: das ganze T übernimmt die persönliche Akzentfarbe (die vier Kacheln in einem dunkleren Ton derselben Farbe) +- Desktop-App: Beta-Pakete werden nur noch neu gebaut, wenn sich an der Desktop-App etwas geändert hat; sonst bleiben die zuletzt gebauten Pakete gültig, und die App meldet keinen neuen Beta-Stand ## 1.2.0 – 2026-09-17 diff --git a/docs/anleitung-betrieb.md b/docs/anleitung-betrieb.md index ded9bb2..fd2f6e6 100644 --- a/docs/anleitung-betrieb.md +++ b/docs/anleitung-betrieb.md @@ -570,7 +570,37 @@ Der Rust-Bau ist auf vier parallele Prozesse begrenzt (`CARGO_BUILD_JOBS`), weil sich der Runner den Rechner mit Gitea und dem Entwicklungs-Stack teilt; mit acht Prozessen geriet ein Rechner mit 15 GB Arbeitsspeicher an die Grenze. Der Job dauert damit etwa fünf bis sieben Minuten (mit warmem Zwischenspeicher), -der erste Lauf nach einer Änderung der Abhängigkeiten deutlich länger. +der erste Lauf nach einer Änderung der Abhängigkeiten deutlich länger – sofern überhaupt gebaut wird, siehe nächster Abschnitt. + +### Wann gebaut wird und wann Pakete übernommen werden + +Seit September 2026 baut die Pipeline die Desktop-Pakete auf dem Beta-Kanal +nur noch, wenn sich an der Desktop-App etwas geändert hat. Maßgeblich ist ein +Stempel aus der Versionsnummer des letzten Freigabe-Tags und dem letzten +Commit an den Desktop-Pfaden (`apps/desktop/`, die Skripte +`desktop-version.sh`, `desktop-collect.sh`, `desktop-stamp.sh`, die +Workflow-Datei `ci.yml`). Liegen zu diesem Stempel fertige Pakete im +Zwischenspeicher des Runners, übernimmt der Job sie unverändert; die +Bau-Schritte entfallen, und der Job braucht dann unter einer Minute. Im +Protokoll steht dann eine Zeile wie „Desktop unveraendert seit +: Pakete … aus dem Zwischenspeicher". + +Drei Regeln dazu: + +- Freigabe-Tags bauen immer – die Release-Dateien entstehen frisch mit reiner + Versionsnummer. +- Nach einer Freigabe wird einmal neu gebaut, auch ohne Änderung an der + Desktop-App, weil die Versionsnummer zum Stempel gehört; die Beta-Pakete + tragen danach die neue Basisversion. +- Übernommene Pakete tragen den Stand ihres Baus – Dateiname (`-beta.`) + und Manifest nennen den Commit des Baus, nicht den des aktuellen Abbilds. + Das ist gewollt: ein Client dieses Standes bekommt keinen unnötigen Hinweis + auf einen neuen Beta-Stand, ein älterer Client weiterhin. + +Fehlt der Eintrag im Zwischenspeicher (der Runner räumt ungenutzte Einträge +nach einigen Tagen, alte nach etwa einem Monat weg) oder ist er unvollständig, +wird ganz normal gebaut – die Pipeline prüft vor der Übernahme Manifest, +Kanal, Version, Dateinamen, Größen und Prüfsummen. ### Wo die Pakete im Abbild liegen @@ -621,3 +651,4 @@ Für die Desktop-Auslieferung ist keine neue Pflichtvariable nötig. | Download bricht bei großen Dateien ab | Größengrenze oder Zeitlimit des vorgeschalteten Proxys (Nginx Proxy Manager) – `client_max_body_size` bzw. Timeout-Einstellungen | Proxy-Konfiguration für die betroffene Adresse prüfen und die Grenze anheben. | | Client meldet „Unter dieser Adresse antwortet kein Tessera-Server" | Anwender hat die interne API-Adresse statt der Web-Adresse eingetragen, oder `/api-proxy` ist vom Client-Rechner aus nicht erreichbar | Die im Anwenderhandbuch beschriebene Adresse verwenden (dieselbe wie im Browser); Netzwerk-/Firewall-Erreichbarkeit der Web-Adresse prüfen. | | Windows zeigt die SmartScreen-Warnung | Erwartet – die App ist für den internen Gebrauch nicht signiert (D-09) | Kein Fehler; Anwenderhandbuch, Abschnitt „Installation unter Windows", beschreibt den Ablauf. | +| Beta-Paket nennt einen älteren Commit als das laufende Abbild (Dateiname `-beta.`, Einstellungen → Desktop-App) | Erwartet: Desktop-App seit diesem Commit unverändert, Pakete aus dem Zwischenspeicher übernommen (Abschnitt „Wann gebaut wird …") | Kein Fehler. Soll dennoch neu gebaut werden, genügt eine Änderung unter `apps/desktop/` im nächsten Push. | diff --git a/docs/anleitung-entwicklung.md b/docs/anleitung-entwicklung.md index 932552d..c7c9143 100644 --- a/docs/anleitung-entwicklung.md +++ b/docs/anleitung-entwicklung.md @@ -170,6 +170,12 @@ vorgesehen. Sprache, Symbol und Bilder des Installers stehen in sich nur über den CI-Bau auf einem Windows-Rechner prüfen, lokal validiert `cargo check` lediglich die Schlüssel. +**Im CI wird die Desktop-App nur gebaut, wenn sich etwas an ihr geändert hat.** Der Job `desktop` vergleicht einen Stempel aus Versionsnummer und letztem Commit an `apps/desktop/`, `desktop-version.sh`, `desktop-collect.sh`, `desktop-stamp.sh` und `ci.yml` mit dem Zwischenspeicher des Runners und übernimmt bei Treffer die zuletzt gebauten Pakete (Details: `docs/ci-cd-setup.md`, Abschnitt 4). Eine Änderung außerhalb dieser Pfade – etwa nur in `pnpm-lock.yaml` – löst keinen Desktop-Bau aus; soll trotzdem neu gebaut werden, genügt eine Änderung unter `apps/desktop/`. Stempel lokal ansehen: + +```bash +DESKTOP_TAG=v1.2.0 GITHUB_REF=refs/heads/main sh .gitea/scripts/desktop-stamp.sh stamp +``` + ## Architektur im Überblick **Frontend** (`apps/web/src/app`, Next.js App Router): diff --git a/docs/ci-cd-setup.md b/docs/ci-cd-setup.md index 82d3bff..48ab914 100644 --- a/docs/ci-cd-setup.md +++ b/docs/ci-cd-setup.md @@ -138,6 +138,27 @@ Der Job `desktop` baut auf demselben `ubuntu-latest`-Runner nacheinander (ein Cache, ein Runner, siehe `18-CONTEXT.md` Specific Ideas) sowohl das Linux-AppImage als auch -- per Cross-Bau -- den Windows-Installer: +**Ueberspringen bei unveraendertem Desktop (quick-260917-jdh):** Direkt nach +dem Checkout berechnet `desktop-stamp.sh stamp` den Stempel `-` +(Version aus `desktop-version.sh --print`; SHA = letzter Commit an +`apps/desktop`, `desktop-version.sh`, `desktop-collect.sh`, +`desktop-stamp.sh`, `ci.yml` -- Konstante `DESKTOP_PATHS`; `pnpm-lock.yaml` +bewusst nicht, weil die Tauri-CLI-Version an `apps/desktop/package.json` +haengt und der Bau keine Datei ausserhalb von `apps/desktop` liest) und gibt +`skip_allowed=true` nur fuer `refs/heads/main` aus. Danach `actions/cache/restore@v4` +mit dem Schluessel `desktop-dist-stamp-` -- ohne `restore-keys`, weil +`act_runner` auch den Hauptschluessel per Praefix sucht und ein aelterer +Stand nie als Treffer gelten darf. Anschliessend `desktop-stamp.sh check`: +`cache-hit`, Manifest, Kanal `beta`, Version, beide Dateien mit Groesse und +sha256 laut Manifest -> `reuse=true`; sonst raeumt es `desktop-dist/` auf und +gibt `reuse=false`. Alle Bau-Schritte (setup-node bis Pakete einsammeln) +tragen `if: steps.reuse.outputs.reuse != 'true'`. Nach einem echten Bau legt +`actions/cache/save@v4` die Pakete zusaetzlich unter dem Stempel-Schluessel ab +(nur auf `main`). Die Uebergabe an `publish` (`desktop-dist-`) laeuft in +beiden Faellen; `publish` ist unveraendert. Bei Tags `v*` wird weder gesucht +noch abgelegt. Lokale Probe: `DESKTOP_TAG=v1.2.0 GITHUB_REF=refs/heads/main +sh .gitea/scripts/desktop-stamp.sh stamp`. + 1. **Systemabhaengigkeiten** (`apt-get install`): WebKit/Tauri-Pakete (`libwebkit2gtk-4.1-dev` usw.) fuer den Linux-Bau, dazu `lld llvm clang nsis` fuer den Windows-Cross-Bau (der NSIS-Bundler ruft `makensis` aus @@ -166,7 +187,9 @@ Linux-AppImage als auch -- per Cross-Bau -- den Windows-Installer: 7. **Uebergabe an `publish`** per `actions/cache/save@v4` mit dem Schluessel `desktop-dist-${{ gitea.sha }}` (ein neuer Schluessel je Commit, damit `publish` garantiert die Pakete des gerade gebauten Standes bekommt, nicht - einen aelteren Cache-Treffer). + einen aelteren Cache-Treffer). Dieser Schritt laeuft auch dann, wenn der Bau + uebersprungen wurde -- er sichert in diesem Fall den aus dem Stempel-Cache + restaurierten Stand unter dem neuen SHA. **Warum `actions/cache` und nicht `upload-artifact`:** Auf dieser Gitea-Instanz ist `actions/upload-artifact`/`download-artifact` unzuverlaessig @@ -320,6 +343,27 @@ und einen Branch-Schutz fuer `live` anlegen (T-KU1-04). Speicherdruck `CARGO_BUILD_JOBS` (z. B. auf `4`) als Umgebungsvariable im Job setzen, um die parallele Uebersetzung zu drosseln. +### `desktop` baut, obwohl nichts geaendert wurde -- oder uebernimmt trotz Aenderung + +**Baut trotzdem:** + +1. Erster Lauf nach einer Aenderung unter den Desktop-Pfaden -- der Stempel + ist neu, das ist erwartet. +2. Ein neuer Freigabe-Tag ist gesetzt -- die Version im Stempel hat sich + geaendert, die Beta-Pakete muessen einmal neu entstehen. +3. Der Eintrag ist vom Runner-Cache weggeraeumt worden -- `act_runner` raeumt + ungenutzte Eintraege nach einigen Tagen, aeltere nach etwa einem Monat weg. +4. `ci.yml` oder eines der Desktop-Skripte wurde geaendert -- beides gehoert + selbst zur Pfadliste `DESKTOP_PATHS`. +5. `desktop-stamp.sh check` hat den gefundenen Eintrag verworfen -- der Grund + steht im Log des Schritts "Gefundene Pakete pruefen". + +**Uebernimmt trotz Aenderung:** Die Aenderung liegt ausserhalb der Pfadliste +(zum Beispiel nur `pnpm-lock.yaml`). Entweder zusaetzlich etwas unter +`apps/desktop/` aendern, oder `DESKTOP_PATHS` in `.gitea/scripts/desktop-stamp.sh` +um den betroffenen Pfad erweitern -- diese Erweiterung loest selbst einen +Neubau aus, weil `desktop-stamp.sh` Teil der eigenen Pfadliste ist. + ### `publish`: cache miss `actions/cache/restore@v4` mit `fail-on-cache-miss: true` bricht den Job