rinkplanner/docs/updates.md
torsten cbe0bf4963 chore: Version 0.3.0 veröffentlichen (Windows)
Version an allen Stellen auf 0.3.0 erhöht (project.godot, Export-Presets
inkl. Windows-Metadaten und Android-Code, NSIS-Fallbacks) und den
Windows-Installer gebaut und hochgeladen.

- version.json: 0.3.0, Windows-Eintrag mit SHA-256; macOS fehlt bewusst,
  das DMG wird auf einem Mac gebaut.
- Website: neuer Release-Block 0.3.0 mit dem Badge, Datum in Hero und
  Download-Hinweis, Windows-/macOS-Stand getrennt benannt.
- docs/updates.md: aktueller Stand und die macOS-Lücke dokumentiert.
2026-11-13 12:03:40 +01:00

266 lines
12 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-13, veröffentlichte Version **0.3.0** (Windows; macOS folgt).
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.2"
```
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.2.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.2",
"released": "2026-11-12",
"notes": "Neu: …",
"downloads": {
"macos": {
"url": "https://programmschmiede.de/rinkplanner/download/rinkplanner-setup.dmg",
"sha256": "…",
"size": 68091156
},
"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; `./tools/publish_version.sh --windows` veröffentlichen. Bei gleicher Version übernimmt das Skript fehlende Plattform-Einträge aus dem Live-Endpunkt. |
## Aktueller Stand und Übergang
- **0.3.0** ist seit 2026-11-13 für Windows veröffentlicht: Mehrere Saisons
(Regelwerk als Saisonordner mit Invariantenprüfung), Saison an der Kür,
Saison-Vergleich, Artistic als eigener Programmtyp (ohne Punktschätzung)
und die Feature-Grenzen aus ISU 2788. Das macOS-DMG folgt; bis dahin bleibt
die Mac-Version bei 0.2.3 und bekommt keinen Update-Hinweis, weil
`downloads.macos` im Endpunkt fehlt.
- **0.2.3** ist seit 2026-11-12 für macOS und Windows veröffentlicht: Beim
Schließen werden laufende Hintergrund-Verbindungen (Update-Check, Sync)
eingesammelt; ein früher Ausstieg führt nicht mehr zu einem Absturz. Das
DMG wurde nachträglich auf macOS gebaut (siehe
`docs/findings-2026-11-12-headless-crash.md`).
- **0.2.2** ist seit 2026-11-12 für macOS und Windows veröffentlicht: Die
Oberfläche lässt sich über Datei → Sprache auf Englisch umschalten, die
Wahl wird in `user://app.cfg` gespeichert. Übersetzt sind Menüs, Dialoge,
Prüfbericht, Cloud-/Update-Meldungen und die PDF-/SVG-Blätter (Katalog:
`rinkplanner/assets/i18n/strings.csv`).
- **0.2.1** (2026-11-12): neuer Skater im Kürkleid, kontrastreichere
3D-Bande und ein schlankerer Build (frühere Modellvarianten entfernt,
Installer 29 statt 32 MB).
- **macOS** ist seit dem 0.2.2-Release im Endpunkt (DMG, 65 MB); mit 0.2.3
wurde das DMG nachgezogen. `publish_version.sh` übernimmt Einträge anderer
Plattformen nur, wenn die Live-Version zur neuen passt – ein fehlendes DMG
führt also nicht zu einem Hinweis auf eine Version ohne Installer.
- **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 (macOS
und Windows: 0.2.2); 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).
Neu aufgenommen werden nur lokal gebaute Installer; Einträge anderer
Plattformen übernimmt das Skript bei gleicher Version aus dem Live-Endpunkt.
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.