Improve release tooling and documentation

Author: bhack

.github/workflows/ci.yml

@@ -50,6 +50,7 @@ jobs:
 
     outputs:
       flatpak: ${{ steps.filter.outputs.flatpak }}
+      release_metadata: ${{ steps.filter.outputs.release_metadata }}
       test: ${{ steps.filter.outputs.test }}
       tooling: ${{ steps.filter.outputs.tooling }}
       pwg: ${{ steps.filter.outputs.pwg }}
@@ -73,6 +74,7 @@ jobs:
               echo "tooling=true"
               echo "pwg=true"
               echo "flatpak=true"
+              echo "release_metadata=true"
             } >> "$GITHUB_OUTPUT"
           }
 
@@ -84,6 +86,7 @@ jobs:
                   echo "tooling=false"
                   echo "pwg=false"
                   echo "flatpak=false"
+                  echo "release_metadata=false"
                 } >> "$GITHUB_OUTPUT"
                 exit 0
               fi
@@ -110,6 +113,7 @@ jobs:
           tooling=false
           pwg=false
           flatpak=false
+          release_metadata=false
 
           while IFS= read -r path; do
             case "$path" in
@@ -118,11 +122,12 @@ jobs:
                 tooling=true
                 pwg=true
                 flatpak=true
+                release_metadata=true
                 ;;
               README.md|pyproject.toml|MANIFEST.in|src/*|tests/*|data/*|extensions/*)
                 test=true
                 ;;
-              tools/check_gnome_shell_extension.py|tools/pack_gnome_shell_extension.sh)
+              tools/check_gnome_shell_extension.py|tools/pack_gnome_shell_extension.sh|tools/prepare_release.py|tools/release_status.py)
                 test=true
                 ;;
             esac
@@ -133,6 +138,12 @@ jobs:
                 ;;
             esac
 
+            case "$path" in
+              CHANGELOG.md|README.md|MANIFEST.in|pyproject.toml|data/io.github.bhack.mini-eq.metainfo.xml|docs/development.md|docs/flathub.md|docs/release.md|docs/screenshots/README.md|tools/prepare_release.py|tools/release_status.py|tests/test_prepare_release.py|tests/test_release_status.py)
+                release_metadata=true
+                ;;
+            esac
+
             case "$path" in
               .github/workflows/ci.yml|tools/check_pipewire_gobject.py|src/mini_eq/pipewire_backend.py|src/mini_eq/analyzer.py)
                 pwg=true
@@ -151,6 +162,7 @@ jobs:
             echo "tooling=$tooling"
             echo "pwg=$pwg"
             echo "flatpak=$flatpak"
+            echo "release_metadata=$release_metadata"
           } >> "$GITHUB_OUTPUT"
 
           {
@@ -160,8 +172,31 @@ jobs:
             echo "- tooling: \`$tooling\`"
             echo "- pipewire-gobject: \`$pwg\`"
             echo "- flatpak: \`$flatpak\`"
+            echo "- release metadata: \`$release_metadata\`"
           } >> "$GITHUB_STEP_SUMMARY"
 
+  release-metadata:
+    needs: changes
+    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.release_metadata != 'true' }}
+        run: echo "No release metadata changes detected; skipping release metadata status check."
+
+      - name: Check out repository
+        if: ${{ needs.changes.outputs.release_metadata == 'true' }}
+        uses: actions/checkout@v6
+
+      - name: Check local release metadata status
+        if: ${{ needs.changes.outputs.release_metadata == 'true' }}
+        run: python3 tools/release_status.py --no-network
+
   tooling:
     needs: changes
     if: ${{ always() && !(github.event_name == 'workflow_dispatch' && inputs.smoke_only) }}
@@ -180,6 +215,14 @@ jobs:
         if: ${{ needs.changes.outputs.tooling == 'true' }}
         uses: actions/checkout@v6
 
+      - name: Cache pip downloads
+        if: ${{ needs.changes.outputs.tooling == 'true' }}
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: tooling-pip-${{ runner.os }}-${{ hashFiles('pyproject.toml') }}
+          restore-keys: tooling-pip-${{ runner.os }}-
+
       - name: Install Python tooling
         if: ${{ needs.changes.outputs.tooling == 'true' }}
         run: |
@@ -213,6 +256,14 @@ jobs:
         if: ${{ needs.changes.outputs.test == 'true' }}
         uses: actions/checkout@v6
 
+      - name: Cache pip downloads and wheels
+        if: ${{ needs.changes.outputs.test == 'true' }}
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: test-pip-${{ runner.os }}-py3-${{ hashFiles('pyproject.toml') }}
+          restore-keys: test-pip-${{ runner.os }}-py3-
+
       - name: Install system dependencies
         if: ${{ needs.changes.outputs.test == 'true' }}
         run: |

AGENTS.md

@@ -34,6 +34,8 @@ paths in ignored repo-local skills under `.agents/skills/`.
 - `io.github.bhack.mini-eq.yaml`: local Flatpak manifest.
 - `python3-dependencies.yaml`: generated Flatpak Python dependencies.
 - `tests/`: pytest suite for core behavior and non-visual integration seams.
+- `docs/development.md`: source checkout, PyPI, local Flatpak, and extended
+  development test commands.
 
 ## Development Commands
 
@@ -61,15 +63,8 @@ and no-assert tests are candidates for human review, not automatic removals.
 GTK virtual methods, signal callbacks, property bindings, and other framework
 entry points often look unused to static analysis.
 
-For release/package checks:
-
-```bash
-appstreamcli validate --no-net data/io.github.bhack.mini-eq.metainfo.xml
-desktop-file-validate data/io.github.bhack.mini-eq.desktop
-.venv/bin/python tools/check_gnome_shell_extension.py
-.venv/bin/python -m build
-.venv/bin/python -m twine check dist/*
-```
+For source install, PyPI package validation, local Flatpak builds, and extended
+runtime smoke commands, use `docs/development.md`.
 
 The app depends on system GI/audio packages that Python packaging cannot fully
 install: GTK4, Libadwaita, PipeWire, a WirePlumber-managed session, and the
@@ -92,11 +87,9 @@ PipeWire/WirePlumber graph with synthetic playback and AT-SPI UI driving:
 MINI_EQ_RUN_LIVE_UI=1 .venv/bin/python -m pytest tests/test_mini_eq_live_ui_runtime.py -q
 ```
 
-When creating a fresh venv for pip/package validation, build pipewire-gobject in
-a plain wheel-build venv first, then install that wheel into a
-`--system-site-packages` Mini EQ venv. This keeps distro GI bindings visible at
-runtime without making Ubuntu/Debian `g-ir-scanner` import partial `distutils`
-modules from a system-site build venv.
+When creating a fresh venv for pip/package validation, follow
+`docs/development.md` so pipewire-gobject is built in a plain wheel-build venv
+before being installed into a `--system-site-packages` Mini EQ venv.
 
 ## Change Guidelines
 
@@ -166,19 +159,13 @@ Use `docs/social-preview.png` for GitHub and social link previews. This is not a
 Flathub quality-check input, so it may use branded/dark promotional composition,
 but it should be refreshed when the public screenshot changes materially.
 
-Generate the public release screenshot with deterministic demo data:
-
-```bash
-PYTHONPATH=src python3 tools/render_demo_screenshot.py docs/screenshots/mini-eq.png
-PYTHONPATH=src python3 tools/render_demo_screenshot.py docs/screenshots/mini-eq-dark.png --appearance dark
-```
-
 Do not commit screenshots that show personal device names, Bluetooth device
 names, usernames, hostnames, local paths, or private preset names. Prefer
 `tools/render_demo_screenshot.py` over desktop screenshots because it renders
 only the Mini EQ window from deterministic demo data. Keep the public release
 screenshot in the platform-default light appearance unless you are adding
 additional screenshots that intentionally demonstrate other appearance modes.
+Use `docs/screenshots/README.md` for the generation commands.
 
 For visual or adaptive-layout changes, inspect deterministic screenshot
 matrices before considering the work done. Cover the minimum, default, narrow,
@@ -201,31 +188,16 @@ renders on light and dark backgrounds.
 
 ## Release And Security
 
-Use `docs/release.md` as the public release checklist. Before publishing
-release artifacts, verify the rendered README, package URLs, issue tracker,
-license, screenshots, and AppStream metadata.
-During release preparation, verify that version-bearing files agree:
-`pyproject.toml`, `CHANGELOG.md`, and the AppStream release entry and screenshot
-URL. The package `__version__` is derived from release metadata and should not
-be hardcoded separately.
+Use `docs/release.md` as the public release checklist. Use
+`tools/prepare_release.py`, `tools/release_status.py`,
+`tools/run_release_preflight_container.sh`, and
+`tools/release_post_publish.py` for repeatable release checks. Keep
+owner-specific workflow dispatch, deployment approval, and local Flathub merge
+steps in ignored repo-local skills under `.agents/skills/`.
 
-Before publishing artifacts, run the release preflight. Prefer the
-containerized wrapper when the host does not already have the `pipewire-gobject`
-sdist build dependencies installed:
-
-```bash
-tools/run_release_preflight_container.sh
-```
-
-Set `MINI_EQ_FLATHUB_MANIFEST` to a Flathub publishing manifest path when the
-containerized preflight should include the manifest drift check.
 The preflight owns the focused leak scan for `HEAD`, tracked worktree changes,
 and untracked non-ignored text files. Use Gitleaks as an extra check when
-release history or generated artifacts look suspicious:
-
-```bash
-gitleaks git --no-banner --redact .
-```
+release history or generated artifacts look suspicious.
 
 Do not push local scratch branches or local safety tags.
 Do not rewrite public history unless the user explicitly asks for it and accepts

MANIFEST.in

@@ -9,6 +9,7 @@ include src/mini_eq/assets/icons/hicolor/symbolic/apps/*.svg
 include data/*.desktop
 include data/*.metainfo.xml
 include docs/flathub.md
+include docs/development.md
 include docs/performance.md
 include docs/release.md
 include docs/social-preview.png