docs/workflow/release polish

Author: peterpolidoro

.github/workflows/ci.yml

@@ -6,6 +6,9 @@ on:
     branches:
       - main
 
+permissions:
+  contents: read
+
 jobs:
   test:
     name: Tests (${{ matrix.python-version }})

.github/workflows/publish.yml

@@ -3,9 +3,13 @@ name: Publish
 on:
   push:
     tags:
-      - "*"
+      - "*.*.*"
+      - "v*.*.*"
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   build:
     name: Build distribution
@@ -40,7 +44,7 @@ jobs:
 
   publish-to-pypi:
     name: Publish Python distribution to PyPI
-    if: startsWith(github.ref, 'refs/tags/v')
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
     needs:
       - build
     runs-on: ubuntu-latest

.gitignore

@@ -219,4 +219,6 @@ flycheck_*.el
 # Bench outputs
 bench_results*.jsonl
 bench_matrix*.jsonl
+bench_artifacts/
+qspy*.log
 .DS_Store

CHANGELOG.md

@@ -12,3 +12,7 @@
   while still requiring it for serial transport usage
 - added CI and PyPI Trusted Publishing GitHub Actions workflows
 - documented a reproducible release process for PyPI and conda-forge
+- expanded the README with Pixi benchmark usage, JSONL capture, and QSPY log
+  collection guidance for performance characterization
+- relaxed the publish workflow so release tags can be either `7.0.0` or
+  `v7.0.0`

README.md

@@ -159,8 +159,21 @@ pixi install
 pixi run help
 pixi run check
 pixi run release-check
+pixi run qtools-install
+pixi run qspy -c /dev/ttyACM0 -b 115200
+pixi run bench-smoke
+pixi run bench-full --json-out bench_results.jsonl
 ```
 
+Pixi forwards extra arguments after the task name to the underlying command, so
+`pixi run bench-full --json-out bench_results.jsonl --label "lab-a"` works
+as expected and appends one JSON result object for that run.
+
+For the stock transport-agnostic tasks (`all-on`, `all-off`, `bench`,
+`bench-smoke`, and `bench-full`), set `ARENA_ETH_IP` or
+`ARENA_SERIAL_PORT` in your shell before running the task. This is the
+simplest way to choose the transport without rewriting the task command.
+
 ### Plain pip
 
 ```sh
@@ -170,6 +183,81 @@ python -m build
 python -m twine check dist/*
 ```
 
+## Performance characterization workflow
+
+`bench_results.jsonl` stores the host-side benchmark results, while QSPY
+captures the raw firmware QS stream so you can compare those host-side
+measurements with device-side `PERF_*` records such as `PERF_UPD kind=SPF` and
+`PERF_NET`.
+
+A convenient workflow is to keep both artifacts under a single timestamped
+directory.
+
+### Terminal A: start QSPY and capture the raw QS log
+
+```sh
+mkdir -p bench_artifacts/2026-03-13-eth
+pixi run qtools-install
+pixi run qspy -c /dev/ttyACM0 -b 115200 2>&1 | tee bench_artifacts/2026-03-13-eth/qspy.log
+```
+
+PowerShell:
+
+```powershell
+New-Item -ItemType Directory -Force bench_artifacts\2026-03-13-eth | Out-Null
+pixi run qtools-install
+pixi run qspy -c COM3 -b 115200 2>&1 | Tee-Object -FilePath bench_artifacts\2026-03-13-eth\qspy.log
+```
+
+Leave QSPY running while the benchmark executes in a second terminal. Stop it
+after the benchmark completes so the log contains the full run.
+
+### Terminal B: run the host benchmark and append JSONL results
+
+```sh
+export ARENA_ETH_IP=192.168.10.104
+pixi run bench-full \
+  --json-out bench_artifacts/2026-03-13-eth/bench_results.jsonl \
+  --label "fw=7.0.0 host=$(hostname) transport=ethernet"
+```
+
+PowerShell:
+
+```powershell
+$env:ARENA_ETH_IP = "192.168.10.104"
+pixi run bench-full --json-out bench_artifacts\2026-03-13-eth\bench_results.jsonl --label "fw=7.0.0 host=$env:COMPUTERNAME transport=ethernet"
+```
+
+`bench-full` runs the suite plus a streaming phase using
+`patterns/pat0004.pat`. Use `pixi run bench-smoke` first when you want a short
+sanity check before a longer capture. For Ethernet socket-option comparisons,
+`pixi run bench-socket-matrix --ethernet 192.168.10.104 --json-out bench_matrix.jsonl`
+runs the suite across the predefined TCP tuning variants.
+
+### Preserve the artifact bundle
+
+After the run, keep at least:
+
+- `bench_results.jsonl` for host-side timings and metadata
+- `qspy.log` for the raw QS stream
+- a filtered `qspy_perf.log` for quick comparison (optional)
+
+On POSIX you can extract just the performance lines with:
+
+```sh
+grep 'PERF_' bench_artifacts/2026-03-13-eth/qspy.log > bench_artifacts/2026-03-13-eth/qspy_perf.log
+```
+
+PowerShell:
+
+```powershell
+Select-String -Path bench_artifacts\2026-03-13-eth\qspy.log -Pattern 'PERF_' | ForEach-Object { $_.Line } | Set-Content bench_artifacts\2026-03-13-eth\qspy_perf.log
+```
+
+For reproducible comparisons, keep the artifact directory together with the
+firmware commit or tag, host computer, transport, switch/LAN notes, and the
+benchmark label you used.
+
 ## Releasing
 
 The repository includes GitHub Actions workflows for CI and PyPI Trusted
@@ -179,7 +267,8 @@ Recommended release flow:
 
 1. Update `CHANGELOG.md`.
 2. Run `pixi run release-check` or the equivalent pip commands above.
-3. Commit the release changes and create a `vX.Y.Z` tag.
+3. Commit the release changes and create a release tag such as `7.0.0` or
+   `v7.0.0`.
 4. Push the tag to GitHub.
 5. The `publish.yml` workflow builds the wheel and sdist, then publishes them
    to PyPI using Trusted Publishing.

RELEASING.md

@@ -26,15 +26,31 @@ If you use Pixi and `pyproject.toml` changed, regenerate `pixi.lock` with
 The repository includes `.github/workflows/publish.yml`, which is intended for
 GitHub Actions Trusted Publishing.
 
+One-time setup on GitHub:
+
+1. In the repository settings, create a GitHub Actions environment named
+   `pypi`.
+2. Optionally add protection rules or required reviewers if you want a manual
+   approval gate before publishing.
+
 One-time setup on PyPI:
 
 1. Create the `arena-interface` project on PyPI if it does not already exist.
 2. In the PyPI project settings, add a Trusted Publisher for this GitHub
-   repository and workflow.
-3. Push a tag such as `v7.0.0`.
+   repository.
+3. Use workflow filename `publish.yml` and environment name `pypi`.
+
+Release trigger:
+
+1. Push a release tag such as `7.0.0` or `v7.0.0`.
+2. GitHub Actions will build `dist/*` and publish to PyPI without storing a
+   long-lived API token in GitHub secrets.
+3. `workflow_dispatch` is kept as a manual build/debug entry point; the actual
+   PyPI publish step only runs for tag pushes.
 
-After the tag is pushed, GitHub Actions will build `dist/*` and publish to
-PyPI without storing a long-lived API token in GitHub secrets.
+The normal release path is to let GitHub Actions publish via Trusted
+Publishing. Local `twine upload` is only needed if you intentionally want to
+bypass that workflow.
 
 ## Conda-forge