Harden release docs and CI gating

.github/workflows/ci.yml

@@ -284,58 +284,43 @@ jobs:
           path: dist/*
           if-no-files-found: error
 
-  flatpak:
+  flatpak-build:
     needs: changes
-    if: ${{ always() && !(github.event_name == 'workflow_dispatch' && inputs.smoke_only) }}
+    if: ${{ always() && !(github.event_name == 'workflow_dispatch' && inputs.smoke_only) && needs.changes.result == 'success' && needs.changes.outputs.flatpak == 'true' }}
     runs-on: ubuntu-24.04
     timeout-minutes: 60
     container:
       image: ghcr.io/flathub-infra/flatpak-github-actions:gnome-50@sha256:9d3a99bef793cf99f55b0106130e68a781fd0815c8d2954f26e1ac9253b19e57
       options: --privileged
 
     steps:
-      - name: Require change detection
-        if: ${{ needs.changes.result != 'success' }}
-        run: exit 1
-
-      - name: Skip unchanged scope
-        if: ${{ needs.changes.outputs.flatpak != 'true' }}
-        run: echo "No Flatpak-relevant changes detected; skipping Flatpak job work."
-
       - name: Check out repository
-        if: ${{ needs.changes.outputs.flatpak == 'true' }}
         uses: actions/checkout@v6
 
       - name: Configure Flathub remote
-        if: ${{ needs.changes.outputs.flatpak == 'true' }}
         run: |
           flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
           flatpak --user remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
 
       - name: Build Flatpak
-        if: ${{ needs.changes.outputs.flatpak == 'true' }}
         uses: flatpak/flatpak-github-actions/flatpak-builder@401fe28a8384095fc1531b9d320b292f0ee45adb
         with:
           bundle: mini-eq.flatpak
           manifest-path: io.github.bhack.mini-eq.yaml
           upload-artifact: false
 
       - name: Install built Flatpak
-        if: ${{ needs.changes.outputs.flatpak == 'true' }}
         run: flatpak --user install -y ./mini-eq.flatpak
 
       - name: Smoke-test Flatpak CLI
-        if: ${{ needs.changes.outputs.flatpak == 'true' }}
         run: flatpak run io.github.bhack.mini-eq --help
 
       - name: Check pipewire-gobject GI compatibility
-        if: ${{ needs.changes.outputs.flatpak == 'true' }}
         run: |
           flatpak run --filesystem="$PWD":ro --command=python3 io.github.bhack.mini-eq \
             "$PWD/tools/check_pipewire_gobject.py" --expect-version 0.3.4
 
       - name: Smoke-test Flatpak runtime modules
-        if: ${{ needs.changes.outputs.flatpak == 'true' }}
         run: |
           flatpak run --command=python3 io.github.bhack.mini-eq - <<'PY'
           from pathlib import Path
@@ -381,6 +366,30 @@ jobs:
               raise SystemExit(f"missing Python analyzer module(s): {', '.join(missing)}")
           PY
 
+  flatpak:
+    needs:
+      - changes
+      - flatpak-build
+    if: ${{ always() && !(github.event_name == 'workflow_dispatch' && inputs.smoke_only) }}
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Require change detection
+        if: ${{ needs.changes.result != 'success' }}
+        run: exit 1
+
+      - name: Skip unchanged scope
+        if: ${{ needs.changes.outputs.flatpak != 'true' }}
+        run: echo "No Flatpak-relevant changes detected; skipping Flatpak build."
+
+      - name: Require Flatpak build
+        if: ${{ needs.changes.outputs.flatpak == 'true' && needs['flatpak-build'].result != 'success' }}
+        run: exit 1
+
+      - name: Confirm Flatpak build
+        if: ${{ needs.changes.outputs.flatpak == 'true' && needs['flatpak-build'].result == 'success' }}
+        run: echo "Flatpak build passed."
+
   flatpak-runtime-smoke:
     needs: changes
     if: ${{ github.event_name == 'workflow_dispatch' && inputs.flatpak_runtime_smoke }}

docs/release.md

@@ -171,7 +171,12 @@ API tokens. Keep the `pypi` environment protected with required review before
 production publishing.
 
 Install-check TestPyPI artifacts with PyPI enabled for dependencies and pin the
-exact version being validated:
+exact version being validated. Run this in an environment that has the
+`pipewire-gobject` sdist build dependencies, distro GI bindings, and a reachable
+PipeWire session. The release preflight container satisfies those requirements;
+a plain host venv without `glib-2.0`, `gio-2.0`, `gobject-2.0`, and
+`libpipewire-0.3` pkg-config modules is expected to fail while building
+`pipewire-gobject`.
 
 ```bash
 python3 -m venv --system-site-packages /tmp/mini-eq-testpypi
@@ -183,6 +188,12 @@ python3 -m venv --system-site-packages /tmp/mini-eq-testpypi
 /tmp/mini-eq-testpypi/bin/mini-eq --check-deps
 ```
 
+PyPI JSON and project pages can become visible before the Simple API used by
+`pip` has fully propagated. If a just-published version is visible through
+`https://pypi.org/pypi/mini-eq/<version>/json` but `pip install` still reports
+only older versions, wait briefly and retry before treating it as a release
+failure.
+
 Do not add PyGObject as a Mini EQ PyPI dependency. Keep it a distro/runtime
 requirement (`python3-gi`, `python3-gobject`, etc.) so it matches the host
 GObject-Introspection and GTK stack.
@@ -202,8 +213,9 @@ python3 tools/release_post_publish.py "$version"
 `tools/release_post_publish.py` verifies that the GitHub release is no longer a
 draft, asset URLs use the stable tag instead of temporary `untagged-*` draft
 URLs, the remote tag exists, PyPI can see the version, and the downloaded source
-archive SHA-256 matches the GitHub release asset digest. Use the printed source
-archive SHA-256 for the Flathub repository update.
+archive SHA-256 matches the GitHub release asset digest. Do not use draft
+release asset URLs for Flathub; use the printed source archive SHA-256 after
+the GitHub release is published.
 
 ## Flathub Handoff