Align release gates with Flatpak runtime

Author: bhack

.github/workflows/release.yml

@@ -47,11 +47,6 @@ on:
         required: true
         type: boolean
         default: false
-      force_live_ui_runtime_smoke:
-        description: Run the live GTK/AT-SPI/PipeWire smoke even when app-sensitive files did not change.
-        required: true
-        type: boolean
-        default: false
 
 permissions:
   contents: read
@@ -151,48 +146,6 @@ jobs:
             --github-output "$GITHUB_OUTPUT" \
             --github-summary "$GITHUB_STEP_SUMMARY"
 
-  live-ui-risk:
-    name: Detect live UI smoke gate
-    needs: validate-inputs
-    runs-on: ubuntu-24.04
-
-    outputs:
-      required: ${{ steps.detect.outputs.required }}
-      base_tag: ${{ steps.detect.outputs.base_tag }}
-
-    steps:
-      - name: Check out repository
-        uses: actions/checkout@v6
-        with:
-          ref: ${{ inputs.target }}
-          fetch-depth: 0
-
-      - name: Detect app and UI runtime-sensitive changes
-        id: detect
-        env:
-          CREATE_GITHUB_RELEASE: ${{ inputs.create_github_release }}
-          DRY_RUN: ${{ inputs.dry_run }}
-          FORCE_LIVE_UI_RUNTIME_SMOKE: ${{ inputs.force_live_ui_runtime_smoke }}
-          PUBLISH_PYPI: ${{ inputs.publish_pypi }}
-          PUBLISH_TESTPYPI: ${{ inputs.publish_testpypi }}
-          TAG_NAME: ${{ inputs.tag_name }}
-        run: |
-          set -euo pipefail
-
-          release_requested=false
-          if { [ "$CREATE_GITHUB_RELEASE" = "true" ] || [ "$PUBLISH_TESTPYPI" = "true" ] || [ "$PUBLISH_PYPI" = "true" ]; } \
-            && [ "$DRY_RUN" = "false" ]; then
-            release_requested=true
-          fi
-
-          python3 tools/release_runtime_gate.py \
-            --scope live-ui \
-            --tag "$TAG_NAME" \
-            --release-requested "$release_requested" \
-            --force "$FORCE_LIVE_UI_RUNTIME_SMOKE" \
-            --github-output "$GITHUB_OUTPUT" \
-            --github-summary "$GITHUB_STEP_SUMMARY"
-
   flatpak-runtime-smoke:
     name: Flatpak routing runtime smoke
     needs: runtime-risk
@@ -220,58 +173,6 @@ jobs:
       - name: Build and run Flatpak routing runtime smoke
         run: tools/run_flatpak_runtime_smoke_ci.sh
 
-  live-ui-runtime-smoke:
-    name: Live UI runtime smoke
-    needs: live-ui-risk
-    if: ${{ needs['live-ui-risk'].outputs.required == 'true' }}
-    runs-on: ubuntu-24.04
-    timeout-minutes: 90
-
-    steps:
-      - name: Check out repository
-        uses: actions/checkout@v6
-        with:
-          ref: ${{ inputs.target }}
-
-      - name: Install live UI runtime dependencies
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y \
-            appstream \
-            at-spi2-core \
-            build-essential \
-            dbus-user-session \
-            desktop-file-utils \
-            gir1.2-adw-1 \
-            gir1.2-gtk-4.0 \
-            git \
-            gnome-shell \
-            gobject-introspection \
-            libebur128-1 \
-            libgirepository1.0-dev \
-            libglib2.0-dev \
-            libpipewire-0.3-dev \
-            libspa-0.2-modules \
-            meson \
-            ninja-build \
-            pipewire \
-            pipewire-bin \
-            pkg-config \
-            python3 \
-            python3-cairo \
-            python3-dev \
-            python3-gi \
-            python3-numpy \
-            python3-pip \
-            python3-pyatspi \
-            python3-setuptools \
-            python3-venv \
-            patchelf \
-            wireplumber
-
-      - name: Build source environment and run live UI smoke
-        run: tools/run_live_ui_runtime_smoke_ci.sh
-
   runtime-gate:
     name: Require runtime smoke gate
     needs:
@@ -299,33 +200,6 @@ jobs:
             echo "Flatpak routing runtime smoke was not required for this dispatch."
           fi
 
-  live-ui-gate:
-    name: Require live UI smoke gate
-    needs:
-      - live-ui-risk
-      - live-ui-runtime-smoke
-    if: ${{ always() }}
-    runs-on: ubuntu-24.04
-
-    steps:
-      - name: Require live-ui-risk job
-        if: ${{ needs['live-ui-risk'].result != 'success' }}
-        run: exit 1
-
-      - name: Require live UI smoke
-        if: ${{ needs['live-ui-risk'].outputs.required == 'true' && needs['live-ui-runtime-smoke'].result != 'success' }}
-        run: |
-          echo "::error::Live GTK/AT-SPI/PipeWire runtime smoke is required for this release and did not pass."
-          exit 1
-
-      - name: Confirm live UI gate
-        run: |
-          if [ "${{ needs['live-ui-risk'].outputs.required }}" = "true" ]; then
-            echo "Required live UI runtime smoke passed."
-          else
-            echo "Live UI runtime smoke was not required for this dispatch."
-          fi
-
   preflight:
     name: Release preflight
     needs: validate-inputs
@@ -347,7 +221,6 @@ jobs:
     needs:
       - validate-inputs
       - runtime-gate
-      - live-ui-gate
       - preflight
     runs-on: ubuntu-24.04
 

AGENTS.md

@@ -88,8 +88,9 @@ MINI_EQ_RUN_LIVE_UI=1 .venv/bin/python -m pytest tests/test_mini_eq_live_ui_runt
 ```
 
 The live UI smoke is opt-in locally because it needs nested GNOME Shell,
-AT-SPI, PipeWire, and WirePlumber, but it is a blocking `Release` workflow gate
-for app-sensitive publish dispatches.
+AT-SPI, PipeWire, and WirePlumber. Treat it as a maintainer confidence check on
+a supported recent GNOME/GTK stack; the blocking public release runtime gate is
+the Flatpak routing smoke.
 
 For manual GNOME Shell extension testing against an installed Flatpak build,
 run the nested devkit smoke. It loads the extension from this checkout and

README.md

@@ -51,8 +51,8 @@ flatpak install flathub io.github.bhack.mini-eq
 flatpak run io.github.bhack.mini-eq
 ```
 
-PyPI and source installs are available for development or for systems with the
-required GTK, Libadwaita, PyGObject, PipeWire, WirePlumber, and native
+PyPI and source installs are available for development or for systems with a
+recent GTK/Libadwaita stack plus PyGObject, PipeWire, WirePlumber, and native
 pipewire-gobject build/runtime packages already installed:
 
 ```bash
@@ -77,8 +77,8 @@ https://extensions.gnome.org/extension/9803/mini-eq-controls/
 
 Runtime data is stored under `~/.config/mini-eq`.
 
-`pip install mini-eq` installs only the Python package. The system packages
-listed in
+`pip install mini-eq` installs only the Python package. The recent desktop and
+audio system packages listed in
 [Development](https://github.com/bhack/mini-eq/blob/main/docs/development.md)
 are still required for the app to connect to GTK, PipeWire, and the host
 WirePlumber-managed session.

docs/development.md

@@ -6,12 +6,15 @@ commands. The README stays focused on using Mini EQ.
 ## System Dependencies
 
 Mini EQ depends on system desktop/audio packages that Python packaging cannot
-fully install: GTK 4.12+ and Libadwaita 1.7+ GI bindings, PyGObject, PipeWire,
-WirePlumber as the session manager, and the native libraries required by
-pipewire-gobject. Install PyGObject from your distro, such as `python3-gi` or
-`python3-gobject`, rather than adding a PyPI PyGObject dependency to Mini EQ.
+fully install: a recent GTK/Libadwaita GI stack comparable to the supported
+GNOME Flatpak runtime, PyGObject, PipeWire, WirePlumber as the session manager,
+and the native libraries required by pipewire-gobject. Install PyGObject from
+your distro, such as `python3-gi` or `python3-gobject`, rather than adding a
+PyPI PyGObject dependency to Mini EQ.
 
 If your distro ships older GTK or Libadwaita builds, prefer the Flatpak build.
+The current UI is validated against the GNOME Flatpak runtime; native distro
+installs are best for development on a recent GNOME stack.
 
 Package names vary by distro release. If pip builds pipewire-gobject from its
 source distribution, install the GLib, GObject-Introspection, and PipeWire
@@ -151,8 +154,9 @@ MINI_EQ_RUN_LIVE_UI=1 python3 -m pytest tests/test_mini_eq_live_ui_runtime.py -q
 
 These integration smokes are intentionally separate from the default pytest
 suite because they require nested GNOME Shell, AT-SPI services, PipeWire, and
-WirePlumber. The release workflow promotes the live UI smoke to a blocking gate
-for app-sensitive publish dispatches.
+WirePlumber. Use the live UI smoke as a maintainer confidence check on a
+supported recent GNOME/GTK stack; the public release workflow does not treat
+the hosted Ubuntu native GTK stack as the blocking UI runtime.
 
 ## Local Flatpak Build
 

docs/release.md

@@ -14,15 +14,16 @@ Run the narrowest gate that covers the release risk:
 - **Always:** version metadata, release preflight, GitHub release dry run or
   release workflow, TestPyPI install validation, PyPI publish, post-publish
   verification, then Flathub stable PR.
-- **When application code, UI code, or runtime-sensitive packaging changed:**
-  live GTK/AT-SPI/PipeWire smoke. Public release workflow dispatches run this
-  as a blocking job for app-sensitive changes before building publishable
-  artifacts.
 - **When PipeWire, routing, analyzer, Flatpak permissions, runtime dependencies,
   or shutdown changed:** local Flatpak install, Flatpak runtime smoke, and
   interactive real-music testing before merge or release. Public release
   workflow dispatches also run the isolated Flatpak routing smoke as a blocking
   job when runtime-sensitive files changed since the previous release tag.
+- **When application code, UI code, or state-machine behavior changed:** run the
+  live GTK/AT-SPI/PipeWire smoke on a supported recent GNOME/GTK stack before
+  release. The hosted native Ubuntu runner is not the supported Flatpak runtime,
+  so this smoke is a maintainer confidence gate rather than a blocking public
+  release job.
 - **When background mode, Start at Login, hidden-window lifecycle, or Shell
   control changed:** one clean-permission Flatpak portal smoke in a real GNOME
   session.
@@ -88,7 +89,7 @@ graph behaves correctly. Treat their claims narrowly:
   restore a synthetic stream in an isolated PipeWire/WirePlumber graph.
 - The live UI smoke verifies the real GTK app can be driven through AT-SPI
   while PipeWire routing, output following, monitor capture, preset reset, and
-  shutdown are exercised.
+  shutdown are exercised on the local GNOME/GTK stack used for the smoke.
 - Manual real-session audio testing is still required for changes that depend
   on host devices, real music playback, WirePlumber policy, or analyzer
   behavior users can perceive.
@@ -212,7 +213,8 @@ run the app interactively with real music before release. Exercise
 enable/disable, output switching, preset changes, analyzer display, shutdown,
 and stream restoration against the actual desktop audio graph.
 
-Before the manual real-music pass, run the live UI smoke. It starts a private
+Before the manual real-music pass for app or UI behavior changes, run the live
+UI smoke on a supported recent GNOME/GTK stack. It starts a private
 PipeWire/WirePlumber graph, synthetic playback, nested headless GNOME Shell,
 the real Mini EQ GTK process, and AT-SPI UI controls:
 
@@ -221,17 +223,18 @@ python3 tools/check_live_ui_runtime.py --timeout 35 --cycles 1
 MINI_EQ_RUN_LIVE_UI=1 python3 -m pytest tests/test_mini_eq_live_ui_runtime.py -q
 ```
 
-The `Release` workflow runs this live UI smoke as a blocking job for app and UI
-runtime-sensitive publish dispatches. The pytest wrapper remains opt-in for
-local development so ordinary unit test runs stay fast and do not require
-nested GNOME Shell or AT-SPI services.
+The pytest wrapper remains opt-in for local development so ordinary unit test
+runs stay fast and do not require nested GNOME Shell or AT-SPI services. The
+hosted native Ubuntu runner is useful for smoke-harness work, but it is not the
+supported Flatpak runtime and is not a release-blocking UI authority.
 
 There is an optional hosted Flatpak runtime smoke path in the `CI` workflow.
 Use it as extra signal or for smoke-harness work; keep the local runtime smoke
 as the release check when app/runtime routing behavior changed. The `Release`
 workflow also runs release preflight as a blocking job and has its own blocking
-copy of the Flatpak routing smoke and live UI smoke gates for public TestPyPI,
-PyPI, and GitHub release dispatches.
+copy of the Flatpak routing smoke gate for public TestPyPI, PyPI, and GitHub
+release dispatches. A future Flatpak/GNOME-runtime UI smoke can become
+blocking once it drives the installed Flatpak instead of the host GTK stack.
 
 ## Package Channels
 

src/mini_eq/deps.py

@@ -32,8 +32,8 @@
 )
 PYGOBJECT_HINT = "Ubuntu/Debian: python3-gi; Fedora: python3-gobject; Arch: python-gobject"
 PYCAIRO_HINT = "Ubuntu/Debian: python3-cairo; Fedora: python3-cairo; Arch: python-cairo"
-GTK_HINT = "Ubuntu/Debian: gir1.2-gtk-4.0; Fedora: gtk4; Arch: gtk4. Requires GTK 4.12+."
-ADW_HINT = "Ubuntu/Debian: gir1.2-adw-1; Fedora: libadwaita; Arch: libadwaita. Requires Libadwaita 1.7+."
+GTK_HINT = "Ubuntu/Debian: gir1.2-gtk-4.0; Fedora: gtk4; Arch: gtk4. Prefer the Flatpak on older GTK stacks."
+ADW_HINT = "Ubuntu/Debian: gir1.2-adw-1; Fedora: libadwaita; Arch: libadwaita. Prefer the Flatpak on older stacks."
 PWG_HINT = (
     "Install pipewire-gobject from PyPI or your distribution. "
     "It also needs system libpipewire-0.3, GLib, GObject, GIO, and PyGObject."
@@ -375,7 +375,7 @@ def collect_dependency_checks() -> list[DependencyCheck]:
         check_python_version(),
         check_python_import("gi", "PyGObject", True, PYGOBJECT_HINT),
         check_python_import("cairo", "pycairo", True, PYCAIRO_HINT),
-        check_gi_repository_attribute("Gtk", "4.0", "Button.set_can_shrink", "GTK 4.12+ GI namespace", True, GTK_HINT),
+        check_gi_repository_attribute("Gtk", "4.0", "Button.set_can_shrink", "GTK 4 GI namespace", True, GTK_HINT),
         check_gi_repository("Gdk", "4.0", "GDK 4 GI namespace", True, GTK_HINT),
         check_gi_repository("Gsk", "4.0", "GSK 4 GI namespace", True, GTK_HINT),
         check_gi_repository("Graphene", "1.0", "Graphene GI namespace", True, GTK_HINT),

tests/test_github_workflows.py

@@ -32,17 +32,14 @@ def test_release_workflow_blocks_publish_on_runtime_gate() -> None:
     assert "runtime-gate" in release_yml.partition("build:")[2].partition("runs-on:")[0]
 
 
-def test_release_workflow_blocks_publish_on_live_ui_gate() -> None:
+def test_release_workflow_does_not_block_publish_on_native_live_ui_gate() -> None:
     release_yml = workflow_text("release.yml")
 
-    assert "force_live_ui_runtime_smoke" in release_yml
-    assert "--scope live-ui" in release_yml
-    assert "live-ui-risk:" in release_yml
-    assert "live-ui-runtime-smoke:" in release_yml
-    assert "live-ui-gate:" in release_yml
-    assert "tools/run_live_ui_runtime_smoke_ci.sh" in release_yml
-    assert "needs['live-ui-runtime-smoke'].result != 'success'" in release_yml
-    assert "live-ui-gate" in release_yml.partition("build:")[2].partition("runs-on:")[0]
+    assert "force_live_ui_runtime_smoke" not in release_yml
+    assert "--scope live-ui" not in release_yml
+    assert "live-ui-runtime-smoke:" not in release_yml
+    assert "live-ui-gate:" not in release_yml
+    assert "tools/run_live_ui_runtime_smoke_ci.sh" not in release_yml
 
 
 def test_release_workflow_blocks_publish_on_release_preflight() -> None:
@@ -64,11 +61,11 @@ def test_ci_scope_treats_release_workflow_and_release_gate_tools_as_tested_chang
 
 
 def test_live_ui_runtime_smoke_uses_host_gir_build_environment() -> None:
-    release_yml = workflow_text("release.yml")
     ci_yml = workflow_text("ci.yml")
     script = (ROOT / "tools/run_live_ui_runtime_smoke_ci.sh").read_text(encoding="utf-8")
 
-    assert "patchelf" in release_yml
     assert "patchelf" in ci_yml
     assert "pipewire-gobject" in script
     assert "--no-build-isolation" in script
+    assert "pip install -e ." in script
+    assert ".[dev]" not in script

tools/release_preflight.py

@@ -200,8 +200,9 @@ def run_live_ui_runtime_smoke_notice() -> None:
     for path in changes:
         print(f"  {path}")
     print(
-        "Run the live GTK/AT-SPI/PipeWire smoke before releasing this change. "
-        "The Release workflow also blocks public publish dispatches on this smoke."
+        "Run the live GTK/AT-SPI/PipeWire smoke on a supported recent GNOME/GTK stack before "
+        "releasing this change. The Release workflow does not treat the hosted native Ubuntu GTK "
+        "stack as the blocking UI runtime."
     )
 
 

tools/run_live_ui_runtime_smoke_ci.sh

@@ -29,7 +29,7 @@ PY
 )"
 "$venv/bin/python" -m pip install "meson-python>=0.18" "meson>=1.2" ninja packaging
 "$venv/bin/python" -m pip install --no-build-isolation "$pwg_requirement"
-"$venv/bin/python" -m pip install -e '.[dev]'
+"$venv/bin/python" -m pip install -e .
 "$venv/bin/python" tools/check_live_ui_runtime.py \
   --timeout "$timeout" \
   --cycles "$cycles" \