docs(release): make demo smoke validation pragmatic and CI-friendly

Author: Beowolve

CHANGELOG.md

@@ -27,6 +27,7 @@ The changelog is grouped by release tags (`vX.Y.Z`) and includes an `Unreleased`
 
 ### Documentation
 - ✅ Added an explicit release-readiness version lane plan (`0.5.x` to `0.9.x`) and documented the policy split between continuous release readiness (`0.x`) and controlled public launch (`1.0.0`).
+- ✅ Refined demo smoke validation guidance in `RELEASING.md` to a pragmatic policy: required local-OS smoke per RC, cross-OS checks as nice-to-have, per-OS start commands/checklist, and optional CI startup-smoke scope.
 - ✅ Updated roadmap/status/done docs to mark the `DockDebugOverlay` HUD fixes follow-up as completed (while noting the MainDemo HUD remains opt-in) and return current priority focus to the Phase 3 UX backlog.
 
 ## v0.4.0 - 2026-02-25

DONE.md

@@ -291,6 +291,7 @@ SnapFX has been fully implemented with core functionality and is production-read
 - ✅ Added GitHub Actions release workflow for `v*` tags that runs build/tests and publishes GitHub Releases with distribution artifacts.
 - ✅ Aligned release workflow build tasks and artifact upload paths with split modules (`:snapfx-demo:distZip`/`:distTar`, `snapfx-demo/build/distributions/*`, `snapfx-core/build/libs/*`)
 - ✅ Extended the release workflow with a cross-platform matrix that builds demo `jpackage` ZIP assets on Windows/macOS/Linux and publishes them with OS-specific filenames.
+- ✅ Added a pragmatic demo smoke-validation policy in `RELEASING.md`: at least one local OS smoke run is required per RC, cross-OS manual checks are nice-to-have, per-OS start commands/checklist are documented, and optional CI startup-smoke scope is defined.
 - ✅ Added `org.beryx.jlink` demo packaging baseline in `snapfx-demo` (`jlink`, `jpackageImage`, and `packageJPackageImageZip`) with jpackage-safe version normalization for git-derived dev versions (including a temporary macOS-compatible app-version major floor `1`, planned to be removed at first `v1.x`) and OS-specific app icon wiring (`snapfx.ico`/`snapfx.icns`/`snapfx.png`)
 - ✅ Added `git-cliff` release-note generation (`cliff.toml`) and wired release workflow to publish generated notes.
 - ✅ Tracked `gradlew` as executable (`100755`) so Linux CI/release runners can execute the Gradle wrapper reliably.

RELEASING.md

@@ -72,6 +72,38 @@ Optional push using helper:
   - `snapfx-demo-jpackage-image-macos-<tag>.zip`
   - `snapfx-demo-jpackage-image-linux-<tag>.zip`
 
+## Demo Smoke Validation (Per OS)
+
+Use these commands after unpacking `snapfx-demo-jpackage-image-<os>-<tag>.zip`:
+
+- Windows:
+  - `.\SnapFX-Demo\bin\SnapFX-Demo.exe`
+- macOS:
+  - `open ./SnapFX-Demo.app`
+- Linux:
+  - `chmod +x ./SnapFX-Demo/bin/SnapFX-Demo`
+  - `./SnapFX-Demo/bin/SnapFX-Demo`
+
+Smoke policy:
+- Required: validate the package on at least one local/developer OS environment per release candidate.
+- Nice to have: validate additional OS packages manually when hardware/VMs are available.
+- Covered by CI: release pipeline already builds/packages all OS artifacts; manual smoke exists to detect runtime UX regressions not covered by build success alone.
+
+Minimum smoke checklist for the tested OS package(s):
+- App starts without local JDK installation.
+- Main window opens with expected default layout.
+- One basic interaction works (for example moving a panel tab and closing/reopening a node).
+- App exits cleanly without crash dialog.
+
+### Optional CI Startup Smoke (Recommended)
+
+Feasible CI automation scope:
+- Start the packaged demo executable/app image per OS in a short timeout window.
+- Verify process startup and non-crash exit path (or controlled termination after successful start probe).
+
+Out of scope for pure CI startup smoke:
+- Rich GUI interaction checks like drag-and-drop UX parity across OS (these remain manual or require dedicated UI automation infrastructure).
+
 ## Release Notes
 
 - Release notes are generated with `git-cliff` (`cliff.toml`).

ROADMAP.md

@@ -405,6 +405,7 @@ This roadmap keeps a high-level progress view plus planned/proposed work; detail
 - 📋 **Maven Central**: Publish to Maven Central
 - ✅ **jlink support baseline**: `snapfx-demo` now uses `org.beryx.jlink` and provides `:snapfx-demo:jlink` runtime-image packaging
 - 🚧 **jpackage support baseline**: `snapfx-demo` now provides `:snapfx-demo:jpackageImage` and `:snapfx-demo:packageJPackageImageZip` with OS-specific app icon selection (`.ico`/`.icns`/`.png`) plus macOS-compatible app-version normalization (major version floor `1`), and release automation now publishes per-OS demo ZIP assets (Windows/macOS/Linux); installer generation/signing remains pending
+- ✅ **Smoke validation policy baseline**: `RELEASING.md` now defines required local-OS smoke validation per RC, cross-OS checks as nice-to-have, per-OS start commands/checklist, and optional CI startup-smoke scope (validated against successful `v0.4.1-rc.2` release workflow run).
 - 📋 **Remove temporary macOS appVersion workaround at v1.x**: After the first real `v1.x` project release, drop the major-floor mapping so demo appVersion equals the core/project version again.
 - 📋 **Version management**: Semantic versioning
 

STATUS.md

@@ -16,6 +16,7 @@
 ✅ **Release Module-Split Alignment**: Tag release workflow now builds `:snapfx-demo` distributions explicitly and publishes artifacts from split module output paths
 ✅ **Demo Runtime Packaging Baseline**: `org.beryx.jlink` now configures `:snapfx-demo:jlink`, `:snapfx-demo:jpackageImage`, and `:snapfx-demo:packageJPackageImageZip`, including OS-specific app icons (`.ico`/`.icns`/`.png`) and a temporary macOS-compatible jpackage app-version normalization (major version floor `1`, planned removal at first `v1.x` release)
 ✅ **Cross-Platform Demo Release Assets**: Tag releases now build `jpackage` demo ZIPs on Windows/macOS/Linux and publish them with deterministic OS-specific filenames (`snapfx-demo-jpackage-image-<os>-<tag>.zip`)
+✅ **Release Smoke Validation Baseline**: `RELEASING.md` now defines a practical smoke policy (required on at least one local OS, cross-OS manual checks as nice-to-have) plus per-OS start commands and a minimal checklist; an optional CI startup-smoke scope is documented.
 
 ✅ **Release-Ready Version Strategy**: Roadmap/releasing docs now define an explicit `0.5.x` to `0.9.x` readiness lane with RC drill tags and a controlled `1.0.0` public-launch cut.