From 6ea43ae1347290f883ae59b55e4265c28f8408de Mon Sep 17 00:00:00 2001 From: Chris Laupama <42254688+chrislaupama@users.noreply.github.com> Date: Wed, 11 Nov 2026 21:15:56 +0000 Subject: [PATCH 1/2] CI: pull requests only restore the SDK download cache; docs match the jobs The engine SDK cache used actions/cache, so a pull request that changed engine/CMakeLists.txt could save a cache main never reads. It is now restored everywhere and saved only by main and the nightly run, after a successful job. The docs now say that macOS takes no screenshot, that the labelled Windows self-test needs a change that reaches the app, and that documentation-only pull requests skip the tests. --- .github/workflows/ci.yml | 24 ++++++++++++++++-------- CONTRIBUTING.md | 5 +++-- docs/building.md | 20 +++++++++++--------- engine/README.md | 13 +++++++------ 4 files changed, 37 insertions(+), 25 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d72a0c23..b08189ec 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -175,18 +175,20 @@ jobs: if [ "$RUNNER_OS" = "Windows" ]; then cl 2>&1 | head -1; else c++ --version | head -1; fi echo "CARGO_TARGET_DIR=$GITHUB_WORKSPACE/target" >> "$GITHUB_ENV" echo "DSTUDIO_DEPS_DIR=$GITHUB_WORKSPACE/.deps" >> "$GITHUB_ENV" - - name: Cache SDK downloads + # The SDK downloads, the cargo target dir (debug builds only in this + # job) and the ccache store are restored on every run but saved only by + # pushes to main and the nightly run. Pull requests then start from + # main's latest build, and their own saves cannot fill the repository's + # 10 GB cache and evict main's. + - name: Restore SDK downloads + id: deps-cache if: steps.changes.outputs.engine == 'true' - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 with: path: .deps key: deps-${{ runner.os }}-${{ hashFiles('engine/CMakeLists.txt') }} - # The cargo target dir (debug builds only in this job) and the ccache - # store are restored on every run but saved only by pushes to main and - # the nightly run, under a new key each time. Pull requests then start - # from main's latest build, and their own saves cannot fill the - # repository's 10 GB cache and evict main's. The cargo-v2 fallback is the - # layout before the tests/app split (one cache with both profiles). + # The cargo and ccache keys are new on every save. The cargo-v2 fallback + # is the layout before the tests/app split (one cache with both profiles). - name: Restore cargo registry and target if: steps.changes.outputs.run == 'true' id: cargo-cache @@ -259,6 +261,12 @@ jobs: - name: ccache statistics if: steps.changes.outputs.run == 'true' && !cancelled() run: ccache --show-stats + - name: Save SDK downloads + if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' && steps.changes.outputs.engine == 'true' && steps.deps-cache.outputs.cache-hit != 'true' + uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + with: + path: .deps + key: ${{ steps.deps-cache.outputs.cache-primary-key }} - name: Save cargo registry and target if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' && steps.changes.outputs.run == 'true' && !cancelled() uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 59c410fe..d1767f56 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,10 +30,11 @@ cd engine && cmake --preset default && cmake --build --preset default && ctest - cargo run --release -p dstudio-app -- --self-test --no-audio # drive the real UI through its checks ``` -CI runs the tests and the self-test (not the interactive `--demo`) on macOS, Windows and Linux for every pull request. +CI runs the tests and the self-test (not the interactive `--demo`) on macOS, Windows and Linux for every pull request +that changes code (documentation-only changes skip them). Its runners have no audio device, so the self-test runs with `--no-audio` (Linux also runs it against a headless PipeWire server) and anything that needs audio hardware has to be tested by hand. The Windows self-test takes about -30 minutes under the software renderer, so pull requests run it only with the `windows-self-test` label; main and +30 minutes under the software renderer, so pull requests that change the app run it only with the `windows-self-test` label; main and the nightly run always run it, and a failure fails the job. The engine is built with warnings as errors on clang, MSVC and GCC, so please build on more than one compiler if you can, or check the CI result. diff --git a/docs/building.md b/docs/building.md index 49cc519b..7a858e74 100644 --- a/docs/building.md +++ b/docs/building.md @@ -159,14 +159,16 @@ jobs that run side by side: - **tests (system)** configures and builds the engine with warnings as errors and runs ctest, then builds and tests the Rust workspace (`cargo test --workspace --locked`, debug). -- **app (system)** builds the app in release mode and runs its smoke tests: a - reference-state screenshot and `device-studio --self-test`, which must report - every check passed (`tools/ci/self-test.sh`). macOS runs `--no-audio`; Linux - runs `--no-audio` and `--self-test-audio` side by side under Xvfb with Mesa +- **app (system)** builds the app in release mode and runs its smoke tests. + `device-studio --self-test` must report every check passed + (`tools/ci/self-test.sh`). macOS runs `--self-test --no-audio` (no + screenshot); Linux takes a reference-state screenshot and runs `--no-audio` + and `--self-test-audio`, all three side by side under Xvfb with Mesa lavapipe; Windows takes the screenshot under WARP on every run, and runs the full self-test (about 30 minutes under WARP) on pushes to main, the nightly - run, manual runs, and pull requests labelled `windows-self-test`. The - screenshots and self-test logs are uploaded as an artifact. + run, manual runs, and pull requests labelled `windows-self-test` whose + changes reach the app. The screenshots and self-test logs are uploaded as an + artifact. A **lint** job checks the workflows (actionlint, which also runs shellcheck on their scripts), the scripts in `tools/`, the change detection below and the @@ -188,9 +190,9 @@ main and the nightly run. A job with nothing to do still runs and passes, so the required checks always report. Caches: the cargo registry and target dir (one per system and job, so debug and -release are restored separately) and the ccache store are restored on every run -and saved only by main and the nightly run, so a pull request never writes a -cache another run uses. Every C/C++ compile goes through ccache. Before +release are restored separately), the ccache store and the engine's SDK +downloads are restored on every run and saved only by main and the nightly run, +so a pull request never writes a cache another run uses. Every C/C++ compile goes through ccache. Before building, [`tools/ci/prepare-target.sh`](../tools/ci/prepare-target.sh) makes every source newer than the restored build (so nothing restored is reused for changed code) and reconfigures the engine's CMake tree from scratch. diff --git a/engine/README.md b/engine/README.md index ae334ee0..f6f90f32 100644 --- a/engine/README.md +++ b/engine/README.md @@ -122,11 +122,12 @@ POSIX signal or Windows NTSTATUS exception code). | ctest | all tests, every CI run; device tests skip on the hosted runner (no audio device), run by hand on a Mac | all tests, every CI run; AU tests and device tests skip (no audio endpoint) | all tests, every CI run, against a headless PipeWire server (null sink + loopback); AU tests skip | | Tested on real audio hardware | yes (Core Audio output + duplex, see below) | **no** | **no** (real PipeWire streams in CI, no sound card) | -**CI** (`.github/workflows/ci.yml`) runs one job per OS, all on GitHub-hosted -runners (`macos-latest`, `windows-latest`, `ubuntu-latest`), none with an -audio device. Each job builds the engine with warnings as errors, runs +**CI** (`.github/workflows/ci.yml`) runs on GitHub-hosted runners +(`macos-latest`, `windows-latest`, `ubuntu-latest`), none with an audio +device. On each system it builds the engine with warnings as errors, runs ctest, builds and tests the Rust workspace and runs the app's -`--self-test --no-audio`. +`--self-test --no-audio`. Pushes to main and the nightly run do all of it; +a pull request runs the parts its changes reach (see docs/building.md). The app (`crates/dstudio-app`) builds on all three. The hosted jobs run it without a GPU or audio device: on Linux under Xvfb with Mesa lavapipe (software Vulkan; @@ -134,8 +135,8 @@ without a GPU or audio device: on Linux under Xvfb with Mesa lavapipe (software --no-audio` (125 checks pass; the 21 checks of the Audio Unit devices section are reported as skipped off macOS), as a required step; on Windows with WARP (DX12 software adapter) the same, also failing the job when a check fails (the -full self-test runs on main, nightly and labelled pull requests; see -docs/building.md): the screenshot renders and the self-test passes, but the +full self-test runs on main, nightly and labelled pull requests that change +the app; see docs/building.md): the screenshot renders and the self-test passes, but the process exits with code 0x87A after the run (not yet explained; macOS/Linux exit 0), so CI prints that exit code and checks the summary line instead. Debug builds of the app abort at exit on every OS (pre-existing: wgpu-core's From d7c107fbfdde7503e3ed76ac04928b454c24f0bf Mon Sep 17 00:00:00 2001 From: Chris Laupama <42254688+chrislaupama@users.noreply.github.com> Date: Wed, 11 Nov 2026 21:21:13 +0000 Subject: [PATCH 2/2] Docs: the engine table and CONTRIBUTING describe path-selected CI --- CONTRIBUTING.md | 5 +++-- engine/README.md | 4 ++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d1767f56..4af994d5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,8 +30,9 @@ cd engine && cmake --preset default && cmake --build --preset default && ctest - cargo run --release -p dstudio-app -- --self-test --no-audio # drive the real UI through its checks ``` -CI runs the tests and the self-test (not the interactive `--demo`) on macOS, Windows and Linux for every pull request -that changes code (documentation-only changes skip them). +CI runs the tests and the self-test (not the interactive `--demo`) on macOS, Windows and Linux. A pull request runs the +parts its changes reach: documentation-only changes run none, engine-test-only changes skip the Rust tests and the app, +and anything CI can't classify runs everything (the rules are in docs/building.md). Its runners have no audio device, so the self-test runs with `--no-audio` (Linux also runs it against a headless PipeWire server) and anything that needs audio hardware has to be tested by hand. The Windows self-test takes about 30 minutes under the software renderer, so pull requests that change the app run it only with the `windows-self-test` label; main and diff --git a/engine/README.md b/engine/README.md index f6f90f32..7f07c7a7 100644 --- a/engine/README.md +++ b/engine/README.md @@ -118,8 +118,8 @@ POSIX signal or Windows NTSTATUS exception code). | Plugin editors | NSWindow (AU/VST3/CLAP) | top-level HWND hosting the plugin child window (VST3 `kPlatformTypeHWND`, CLAP `win32`) | X11 top-level window hosting the plugin window (VST3 `kPlatformTypeX11EmbedWindowID`, CLAP `x11`), XWayland on Wayland; see [Plugins on Windows and Linux](#plugins-on-windows-and-linux) | | Scanner children | `posix_spawn` | `CreateProcessW` (no WER dialogs in the child) | `posix_spawn` | | Test plugins | `.clap`/`.vst3` bundles | `.clap` DLL, `.vst3/Contents/x86_64-win/*.vst3`, + `DStudioTestGui.clap` | `.clap` .so, `.vst3/Contents/x86_64-linux/*.so` | -| Built with warnings as errors | yes (clang, `-Werror`), every CI run | yes (`/W4 /WX`), every CI run | yes (GCC, `-Werror`), every CI run | -| ctest | all tests, every CI run; device tests skip on the hosted runner (no audio device), run by hand on a Mac | all tests, every CI run; AU tests and device tests skip (no audio endpoint) | all tests, every CI run, against a headless PipeWire server (null sink + loopback); AU tests skip | +| Built with warnings as errors | yes (clang, `-Werror`) in CI | yes (`/W4 /WX`) in CI | yes (GCC, `-Werror`) in CI | +| ctest | all tests in CI; device tests skip on the hosted runner (no audio device), run by hand on a Mac | all tests in CI; AU tests and device tests skip (no audio endpoint) | all tests in CI, against a headless PipeWire server (null sink + loopback); AU tests skip | | Tested on real audio hardware | yes (Core Audio output + duplex, see below) | **no** | **no** (real PipeWire streams in CI, no sound card) | **CI** (`.github/workflows/ci.yml`) runs on GitHub-hosted runners