php-qml/CHANGELOG.md

# Changelog

All notable changes to this project are documented here.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Pre-v1.0.0, minor bumps may break public API.

## [Unreleased]

### Added

- (none yet — next changes land here)

## [0.1.0] — 2026-05-03

First public preview. Phases 0 through 4a in PLAN.md are complete plus the Phase 5 DX-polish sub-commits. Linux is the only packaged target; macOS and Windows are deferred to 4b / 4c. Tagging is the user's call (release CI runs on `v*` tags).

### Added

- **Process-pair architecture.** Qt/QML host owns rendering; bundled FrankenPHP child runs the Symfony app in worker mode. They communicate via local HTTP and Mercure SSE.
- **Symfony bundle (`php-qml/bridge`).** `BridgeBundle` wires Doctrine subscriber, `ModelPublisher`, `bridge:doctor` console command, and the `#[BridgeResource]` attribute so app code stays idiomatic Symfony.
- **Qt module (`PhpQml.Bridge`).** `BackendConnection` (lifecycle + Update Semantics state machine: Connecting / Online / Reconnecting / Offline), `RestClient`, `MercureClient`, `ReactiveListModel`, `ReactiveObject`, `AppShell`, `SingleInstance` (QLocalServer-backed lock with launch-arg forwarding), `DevConsole`.
- **Update Semantics.** Optimistic mutations with `Idempotency-Key` round-tripped to Mercure as `correlationKey`; in-flight `pending` role; offline overlay + reconnecting banner via `AppShell`.
- **Headline makers** (`symfony/maker-bundle`):
  - `make:bridge:resource <Name>` — entity (`#[BridgeResource]` + UUIDv7 by default, `--int-id` for auto-increment), CRUD controller, starter `<Name>List.qml`.
  - `make:bridge:command <Name>` — controller stub for non-CRUD endpoints.
  - `make:bridge:window <Name>` — second-window QML scaffold.
- **Skeleton application** (`framework/skeleton`) — minimal reference app exercised by every CI job.
- **POC todo app** (`examples/todo`) — full list UI, multi-window mirror, mark-all-done command, end-to-end test of multi-window coherence and crash-recovery.
- **bundled mode.** When `BRIDGE_URL` is unset (typical AppImage case), `BackendConnection` spawns the embedded FrankenPHP, generates a per-session bearer token, runs first-launch migrations into `~/.local/share/<app>/var/data.sqlite`, and supervises the child with `prctl(PR_SET_PDEATHSIG, SIGTERM)` for cleanup safety.
- **Linux AppImage packaging.** `packaging/linux/build-appimage.sh` + `make appimage` produce a single ~150 MB binary (Qt + Symfony + FrankenPHP + AppImageUpdate sidecar).
- **AppImageUpdate auto-update.** Embedded `update-info` ELF section points at the canonical Gitea Releases URL. `BackendConnection.checkForUpdates()` / `applyUpdate()` invoke the bundled sidecar.
- **Release CI** (`.gitea/workflows/release.yml`). Triggers on `v*` tags. Builds the AppImage, runs `tests/perfsmoke.sh` against PLAN.md §11 budgets (bundle ≤ 200 MB, cold start ≤ 4 s on shared CI runners, idle RSS ≤ 200 MB), generates zsync metadata + `latest.json` appcast + `SHA256SUMS`, optionally GPG-signs them, and uploads everything to the Gitea Release.
- **Quality CI** (`.gitea/workflows/ci.yml`). PHPStan + php-cs-fixer (check) + PHPUnit + qmllint + maker snapshot test + bridge-integration test (HTTP/SSE round-trip + crash-recover) on every push to `main`.
- **DX polish (Phase 5):**
  - `DevConsole.qml` — opt-in window into the bundled FrankenPHP child's merged stdout/stderr; 500-line ring buffer; `Ctrl+`` toggles it in skeleton + todo example.
  - `bin/php-qml-init <name>` — bash scaffolder. Copies `framework/skeleton/`, rewrites identifiers, repoints the path-composer-repo and CMake `add_subdirectory(framework/qml)` reference, runs `composer install` and migrations. `--vendor` produces a portable copy.
  - `.vscode/launch.json` + `tasks.json` + `settings.json` and `.idea/runConfigurations/` shipped with skeleton and todo example.
  - Hot-reload story documented end-to-end (FrankenPHP `--watch`, Qt Creator Reload, `qmlls` live preview).

### Notes

- Tooling versions enforced: PHP 8.4+, Symfony 8, Doctrine ORM 3, Qt 6.5+, FrankenPHP 1.12.2.
- The bundle ships without `composer.lock` (it's a library); the skeleton and the todo example carry their own.
- Licensed under **LGPL-3.0-or-later** (`LICENSE` + `LICENSE.GPL` at the repo root). Chosen to align with Qt 6's LGPLv3 licensing — see PLAN.md §12 for the relinkability obligations the AppImage build already honours.

[Unreleased]: https://src.bundespruefstelle.ch/magdev/php-qml/compare/v0.1.0...HEAD
[0.1.0]: https://src.bundespruefstelle.ch/magdev/php-qml/releases/tag/v0.1.0