rinkplanner/docs/updates.md
torsten 9819311403 feat: Website und Hub zweisprachig (Deutsch/Englisch)
Website (rinkplanner.programmschmiede.de) liegt jetzt im Repo unter web/:
Sprachweiche nach Accept-Language (der User-Agent enthält keine Sprache),
/de/ und /en/ als eigene URLs mit hreflang, Cookie für die manuelle Wahl,
Texte in web/i18n.php, Markup in web/template.php. Deployment über
tools/deploy_web.sh (--sync, --check, --all); /index.html leitet weiter.

Hub: optionale englische Oberfläche über den DE/EN-Umschalter, Cookie
RHUB_LANG, Route /language. Alle Texte (Views, Meldungen, Validierung,
API-messages) stehen in hub/app/i18n_strings.php und laufen über t();
Datum und Zahlen folgen der Sprache. Die API behält ihre code-Felder und
antwortet ohne Cookie weiter deutsch.

deploy_hub.sh --check prüft jetzt Schlüsselparität und fehlende t()-Schlüssel.
Doku: docs/website.md neu, docs/hub.md und AGENTS.md ergänzt.
2026-11-12 22:38:32 +01:00

247 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Updates und Versions-Endpunkt
Stand: 2026-11-12, veröffentlichte Version **0.2.1** (Windows); macOS bleibt bei **0.2.0**.
Die App prüft beim Start und über `Datei → Nach Updates suchen…`, ob eine
neuere Version veröffentlicht ist. Der Endpunkt ist ein statisches JSON auf
der Rinkplanner-Subdomain. Es gibt keinen PHP-Dienst und keine Datenbank.
## Beteiligte Dateien
| Datei | Aufgabe |
| :--- | :--- |
| `rinkplanner/src/core/update/update_info.gd` | Versionsvergleich, JSON-Prüfung, Plattformwahl, gemerkte übersprungene Version |
| `rinkplanner/src/core/update/update_client.gd` | Blockierender HTTPS-Check und Download mit SHA-256-Prüfung |
| `rinkplanner/src/core/update/update_job.gd` | Thread-Aufgabe für Check/Download |
| `rinkplanner/src/whiteboard/ctrl/whiteboard_controller.gd` | Startprüfung, Dialog, menüpunkt, Installation |
| `rinkplanner/scenes/whiteboard/whiteboard.tscn` | `UpdateDialog` mit `UpdateText` |
| `rinkplanner/tests/run_update_tests.gd` | Headless-Tests (kein Netzwerk) |
| `rinkplanner/tests/manual/check_update.gd` | Manueller Check gegen den Live-Endpunkt |
| `tools/publish_version.sh` | Erzeugt `version.json`, bildet Prüfsummen, lädt hoch |
| `docs/updates.md` | Diese Datei |
## Versionsquelle
Die Laufzeitversion steht in `rinkplanner/project.godot`:
```ini
config/version="0.2.0"
```
Beim Versionssprung **alle** Stellen anpassen:
1. `rinkplanner/project.godot`: `config/version`
2. `rinkplanner/export_presets.cfg`:
- Windows: `application/file_version` und `application/product_version`
(viersegmentig, z. B. `0.2.0.0`)
- macOS: `application/short_version` und `application/version`
- Android: `version/name`, außerdem `version/code` erhöhen
3. `tools/windows_installer.nsi` und `tools/export_windows_installer.sh`:
nur Fallback-Werte, falls das Preset nicht gelesen werden kann
`UpdateInfo.current_version()` liest `application/config/version` zur Laufzeit.
Die Tests prüfen, dass der Wert gesetzt und numerisch ist, aber nicht eine
bestimmte Versionsnummer.
## Endpunkt
```
https://rinkplanner.programmschmiede.de/version.json
```
Ablage auf dem Webspace: FTP-Login-Root → Verzeichnis
`rinkplanner.programmschmiede.de/` (Docroot der Subdomain). Die Datei wird
als `application/json` ausgeliefert; es gibt keine Cache-Control-Header.
`version.json` ist die einzige Quelle für die App – die HTML-Seite ist davon
unabhängig.
Schema:
```json
{
"version": "0.2.0",
"released": "2026-11-11",
"notes": "Neu: …",
"downloads": {
"macos": {
"url": "https://programmschmiede.de/rinkplanner/download/rinkplanner-setup.dmg",
"sha256": "…",
"size": 71302221
},
"windows": {
"url": "https://programmschmiede.de/rinkplanner/download/rinkplanner-setup.exe",
"sha256": "…",
"size": 0
}
}
}
```
- `version` ist Pflicht und muss numerisch beginnen (`v`-Präfix und Suffixe
werden ignoriert).
- `downloads` ist Pflicht und darf nicht leer sein; Schlüssel sind `macos`,
`windows`, `linux` (klein geschrieben).
- `url` muss mit `https://` beginnen, sonst wird der Eintrag verworfen.
- `sha256` und `size` sind optional; fehlt `sha256`, wird der Download nicht
verifiziert. Für Releases immer setzen (macht `publish_version.sh`).
- `notes` darf ein String oder eine Liste von Zeilen sein.
- `released` wird als `JJJJ-MM-TT` erwartet und im Dialog als `TT.MM.JJJJ`
angezeigt.
## Veröffentlichen
Voraussetzungen: Installer sind gebaut, `docs/credentials.txt` enthält die
FTP-Zugänge, der Build entspricht der Version in `project.godot`.
```bash
./tools/export_macos_installer.sh
./tools/publish_version.sh --notes "Neu: …"
```
Optionen:
| Option | Wirkung |
| :--- | :--- |
| `--windows` | Nimmt `build/windows/rinkplanner-setup.exe` mit auf. Vorher neu bauen; die Version lässt sich nicht zuverlässig aus der EXE lesen. |
| `--notes "Text"` | Neuerungen für den Update-Dialog. |
| `--no-upload` | Schreibt nur `build/version.json`. |
| `--check` | Gibt den live ausgelieferten Endpunkt aus. |
Das Skript:
1. liest die Version aus `project.godot`,
2. bildet SHA-256 und Größe der vorhandenen Installer,
3. schreibt `build/version.json`,
4. lädt sie per FTP nach `rinkplanner.programmschmiede.de/version.json`,
5. vergleicht die live abgerufene Datei mit der lokalen und bricht bei
Abweichung mit Exit-Code 2 ab (Cache/Hosting prüfen).
Es werden nur Plattformen veröffentlicht, die ausdrücklich vorliegen. Ein
fehlender Eintrag bedeutet: Für diese Plattform gibt es keinen automatischen
Update-Hinweis.
Live prüfen:
```bash
./tools/publish_version.sh --check
curl -fsSL https://rinkplanner.programmschmiede.de/version.json
/Applications/Godot.app/Contents/MacOS/Godot --headless \
--path rinkplanner --script res://tests/manual/check_update.gd
```
Der letzte Befehl nutzt denselben `UpdateClient` wie die App und zeigt
installierte Version, veröffentlichte Version, Plattform und Download-Eintrag.
## Verhalten in der App
- **Automatisch:** nur in exportierten Desktop-Builds
(`OS.has_feature("template")`, nicht Web, Plattform macOS/Windows/Linux).
Editor, Android und die Headless-Tests prüfen nicht automatisch.
- **Manuell:** `Datei → Nach Updates suchen…` funktioniert überall und zeigt
auch „bereits aktuell“ oder Fehler an.
- **Ablauf:** Hintergrund-Thread → Dialog bei neuerer Version → Download nach
`user://updates/` → SHA-256-Prüfung → Installation.
- **Fehler beim automatischen Check** werden nur als Warning geloggt, damit
ein Offline-Start nicht stört. Manuelle Fehler erscheinen im Dialog.
- **„Später“** speichert die übersprungene Version in `user://update.cfg`.
Beim nächsten Start wird dieselbe Version nicht erneut automatisch
gemeldet; manuell schon.
- **Downloadordner:** `user://updates/` (macOS:
`~/Library/Application Support/Godot/app_userdata/Rinkplanner/updates`).
Nach erfolgreicher macOS-Installation wird die DMG gelöscht.
- **Größenlimit:** 512 MB als Schutz vor kaputten Endpunkten.
### Installation je Plattform
- **macOS:** DMG mit `hdiutil attach -nobrowse -readonly` einhängen, die
`.app` im Image per `ditto` über das laufende Bundle kopieren, aushängen,
neue Instanz mit `open -n` starten und die alte beenden. Das Ziel ist das
Bundle, aus dem die App gerade läuft (`OS.get_executable_path()`), nicht
zwangsweise `/Applications`. Schlägt Einhängen oder Kopieren fehl (Rechte,
Translocation, Editor-Lauf), öffnet sich das DMG im Finder mit dem Hinweis,
die App manuell zu ersetzen.
- **Windows:** Der heruntergeladene `rinkplanner-setup.exe` wird gestartet,
die App beendet sich nach ca. einer Sekunde, damit der Installer die
laufende EXE ersetzen kann. Der Installer ist per-user und unsigniert.
- **Linux:** Es gibt noch keinen Installer; die Datei wird im Dateimanager
geöffnet.
## Sicherheit
- Endpunkt und Download nur über HTTPS mit Zertifikatsprüfung
(`TLSOptions.client()`).
- SHA-256 aus dem Endpunkt schützt gegen unvollständige oder vertauschte
Downloads, nicht gegen einen kompromittierten Server. Die Installation
startet erst nach ausdrücklicher Bestätigung.
- Keine Tokens oder Zugangsdaten im Endpunkt. `docs/credentials.txt` bleibt
gitignored.
- macOS-Builds sind ad-hoc signiert und nicht notarisiert. Der Download über
Godot setzt kein Quarantäne-Attribut; falls Gatekeeper dennoch blockiert:
`xattr -cr /Applications/Rinkplanner.app`.
## Tests
```bash
./tools/test.sh # enthält run_update_tests.gd
```
`run_update_tests.gd` deckt ab: Versionsvergleich (auch 0.10 > 0.9), Präfixe
und Suffixe, Plattformzuordnung, JSON-Validierung, HTTPS-Pflicht,
Datumsformat, gemerkte Version und die Dialog-/Menü-Verdrahtung. Es findet
kein Netzwerkzugriff statt.
## Fehlersuche
| Symptom | Ursache/Prüfung |
| :--- | :--- |
| Kein Hinweis in der App | Automatischer Check nur im exportierten Desktop-Build; `--check` am Endpunkt; Version wirklich erhöht? |
| „ungültige Antwort“ | `downloads` fehlt/leer, `version` nicht numerisch oder JSON kaputt. |
| Download startet nicht | `url` ohne `https://`, HTTP-Status ≠ 200, Datei zu groß. |
| „Prüfsumme stimmt nicht“ | Endpunkt und hochgeladener Installer passen nicht zusammen; `publish_version.sh` erneut laufen lassen. |
| Endpunkt liefert Altes | `--check`; ggf. Hosting-Cache; FTP-Ziel `rinkplanner.programmschmiede.de/version.json` prüfen. |
| Windows bekommt keinen Hinweis | Windows-Build fehlt im Endpunkt; mit `--windows` veröffentlichen. |
## Aktueller Stand und Übergang
- **0.2.1** ist seit 2026-11-12 für Windows veröffentlicht: neuer Skater im
Kürkleid, kontrastreichere 3D-Bande und ein schlankerer Build (frühere
Modellvarianten entfernt, Installer 29 statt 32 MB).
- **macOS** bleibt bei 0.2.0. Für macOS gibt es im Endpunkt bewusst keinen
Eintrag; die App zeigt dort keinen Update-Hinweis, bis ein neues DMG gebaut
ist (dauert nur auf macOS).
- **Windows** ist seit 2026-11-11 im Endpunkt; die Installer enthalten die
Update-Prüfung.
- **Übergang von 0.1.0:** Die Version 0.1.0 enthält die Update-Prüfung noch
nicht. Wer sie installiert hat, muss einmal manuell installieren (Windows:
0.2.1, macOS: 0.2.0); danach greifen die Hinweise automatisch.
- Android ist bewusst nicht Teil der automatischen Prüfung.
## „Was ist neu“ auf der Website
Die Rinkplanner-Seite (`https://rinkplanner.programmschmiede.de/`) hat seit
dem 2026-11-12 einen Abschnitt **Was ist neu** mit den letzten Releases. Sie
ist zweisprachig (`/de/`, `/en/`), Quelle im Repo unter `web/` (siehe
`docs/website.md`). Für eine neue Version:
1. In `web/i18n.php` einen neuen Block `release.N.*` oben einfügen (beide
Sprachen!), die Zähler der bestehenden Blöcke nach unten verschieben und
das Badge „Aktuell“/„Current“ zum neuen Block wandern lassen.
2. Download-Texte mitziehen: Datum in `hero.meta` und `downloads.lede`,
Dateigröße in der Windows-/macOS-Karte (steht direkt in
`web/template.php`).
3. Stichpunkte knapp halten und nur belegen, was wirklich drin ist – die
Formulierungen sollen zur `notes`-Zeile in `version.json` passen.
4. `./tools/deploy_web.sh --sync` und danach `--check` laufen lassen.
## Checkliste für das nächste Release
1. Version an allen Stellen erhöhen (siehe oben).
2. `./tools/sync_assets.sh --check` (Assets vorhanden?).
3. `./tools/test.sh`.
4. Installer bauen (`export_macos_installer.sh`, ggf.
`export_windows_installer.sh`).
5. Installer nach `programmschmiede.de/rinkplanner/download/` hochladen.
6. `./tools/publish_version.sh --notes "…"` (und `--windows`, falls gebaut).
7. „Was ist neu“ auf der Website ergänzen (siehe unten).
8. `./tools/publish_version.sh --check` und
`tests/manual/check_update.gd` gegen den Live-Endpunkt laufen lassen.