diff --git a/.github/workflows/_reusable-build.yml b/.github/workflows/_reusable-build.yml index afa1edcd0c..a1ff991619 100644 --- a/.github/workflows/_reusable-build.yml +++ b/.github/workflows/_reusable-build.yml @@ -117,7 +117,7 @@ jobs: if: matrix.os == 'ubuntu-24.04' || matrix.os == 'macos-26' run: | cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DUSE_ONNXRUNTIME=ON -DMNE_WARNINGS_AS_ERRORS=ON - cmake --build build + cmake --build build --parallel "$(nproc 2>/dev/null || sysctl -n hw.logicalcpu)" - name: Configure and compile MNE-CPP (Windows) if: matrix.os == 'windows-2025-vs2026' @@ -128,7 +128,7 @@ jobs: cmd.exe /c "call `"$vcvarsPath`" && set > %temp%\vcvars.txt" Get-Content "$env:temp\vcvars.txt" | Foreach-Object { if ($_ -match "^(.*?)=(.*)$") { Set-Content "env:\$($matches[1])" $matches[2] } } cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DUSE_ONNXRUNTIME=ON -DMNE_WARNINGS_AS_ERRORS=ON - cmake --build build --config Release + cmake --build build --config Release --parallel - name: Deploy binaries run: | diff --git a/.github/workflows/_reusable-tests.yml b/.github/workflows/_reusable-tests.yml index ea449cd1a5..8c3bc4bf8b 100644 --- a/.github/workflows/_reusable-tests.yml +++ b/.github/workflows/_reusable-tests.yml @@ -31,6 +31,16 @@ on: required: false default: false type: boolean + os_json: + description: "JSON list of runner OSes to test on" + required: false + default: '["ubuntu-24.04", "macos-26", "windows-2025-vs2026"]' + type: string + save_ccache: + description: "Save the ccache and prune older entries (needs actions: write)" + required: false + default: false + type: boolean secrets: CODECOV_TOKEN: required: false @@ -46,7 +56,7 @@ jobs: fail-fast: false max-parallel: 3 matrix: - os: [ubuntu-24.04, macos-26, windows-2025-vs2026] + os: ${{ fromJSON(inputs.os_json) }} steps: - name: Clone repository @@ -164,6 +174,39 @@ jobs: run: | python -c "import mne; mne.datasets.sample.data_path()" + # ── Compiler cache (Linux|MacOS) ─────────────────────────────────────── + # One entry per OS/Qt/coverage configuration, capped by CCACHE_MAXSIZE. + # Only callers that pass save_ccache write it, and then delete the entries + # they supersede, so the total stays at a few hundred MB per configuration + # instead of growing with every run and evicting the other Actions caches. + - name: Set up ccache (Linux|MacOS) + if: runner.os != 'Windows' + shell: bash + run: | + if [ "$RUNNER_OS" = "Linux" ]; then + sudo apt-get install -q ccache + else + brew install ccache + fi + { + echo "CCACHE_DIR=$RUNNER_TEMP/ccache" + echo "CCACHE_BASEDIR=$GITHUB_WORKSPACE" + echo "CCACHE_COMPILERCHECK=content" + echo "CCACHE_MAXSIZE=400M" + echo "CMAKE_C_COMPILER_LAUNCHER=ccache" + echo "CMAKE_CXX_COMPILER_LAUNCHER=ccache" + # Coverage only changes the compile on Linux, so macOS shares one key. + echo "CCACHE_KEY_PREFIX=ccache-v1-${{ matrix.os }}-qt${{ inputs.qt_version }}-cov${{ runner.os == 'Linux' && inputs.with_code_coverage }}-" + } >> "$GITHUB_ENV" + + - name: Restore ccache (Linux|MacOS) + if: runner.os != 'Windows' + uses: actions/cache/restore@v5 + with: + path: ${{ runner.temp }}/ccache + key: ${{ env.CCACHE_KEY_PREFIX }}${{ github.run_id }} + restore-keys: ${{ env.CCACHE_KEY_PREFIX }} + # ── Build ────────────────────────────────────────────────────────────── # MNE_WARNINGS_AS_ERRORS enforces release gate G5 for the test build too, so # test sources cannot become the loophole through which warnings return. @@ -211,6 +254,28 @@ jobs: cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON -DMNE_WARNINGS_AS_ERRORS=ON cmake --build build --config Release --parallel + - name: Save ccache (Linux|MacOS) + if: runner.os != 'Windows' && inputs.save_ccache + uses: actions/cache/save@v5 + with: + path: ${{ runner.temp }}/ccache + key: ${{ env.CCACHE_KEY_PREFIX }}${{ github.run_id }} + + - name: Prune superseded ccache entries (Linux|MacOS) + if: runner.os != 'Windows' && inputs.save_ccache + shell: bash + env: + GH_TOKEN: ${{ github.token }} + GH_REPO: ${{ github.repository }} + run: | + ccache --show-stats || true + current="${CCACHE_KEY_PREFIX}${{ github.run_id }}" + gh cache list --key "$CCACHE_KEY_PREFIX" --ref "$GITHUB_REF" --limit 100 --json id,key \ + --jq ".[] | select(.key != \"$current\") | .id" | + while read -r id; do + gh cache delete "$id" || true + done + # ── Run tests ────────────────────────────────────────────────────────── # CTest drives the run from the add_test() registrations rather than from a # glob over the binary output directory. A test that is built but written diff --git a/.github/workflows/_reusable-wasm.yml b/.github/workflows/_reusable-wasm.yml new file mode 100644 index 0000000000..feb8b9651f --- /dev/null +++ b/.github/workflows/_reusable-wasm.yml @@ -0,0 +1,112 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright (c) 2026 MNE-CPP Authors +# Christoph Dinh + +# Builds the WebAssembly applications and examples (Linux only). Callers that +# publish them pass upload_artifact and deploy the "wasm-build" artifact. + +name: Reusable WebAssembly build + +on: + workflow_call: + inputs: + upload_artifact: + description: "Upload out/wasm as the wasm-build artifact" + required: false + default: false + type: boolean + +env: + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true' + +jobs: + WasmBuild: + runs-on: ubuntu-24.04 + + steps: + - name: Clone repository + uses: actions/checkout@v5 + + - name: Install dependencies + run: | + sudo rm -f /etc/apt/sources.list.d/microsoft-*.list /etc/apt/sources.list.d/azure-*.list /etc/apt/sources.list.d/microsoft-*.sources /etc/apt/sources.list.d/azure-*.sources + sudo apt-get update -qq + sudo apt-get install -qq build-essential libgl1-mesa-dev ninja-build + + - name: Setup Emscripten + run: | + cd .. + git clone https://github.com/emscripten-core/emsdk.git + cd emsdk + ./emsdk install 4.0.7 + ./emsdk activate 4.0.7 + + - name: Load external dependency versions + shell: bash + run: ./scripts/ci/load_external_deps.sh + + - name: Download pre-built WASM Qt binaries + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + gh release download qt_binaries -p "qt6_${QT_VERSION_TOKEN}_static_binaries_wasm.tar.gz" -D /tmp + mkdir -p "${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}/wasm_multithread" + tar xf "/tmp/qt6_${QT_VERSION_TOKEN}_static_binaries_wasm.tar.gz" -C "${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}/wasm_multithread" + echo "Qt6_DIR=${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}" >> "$GITHUB_ENV" + + - name: Download host Qt binaries for cross-compilation + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + gh release download qt_binaries -p "qt6_${QT_VERSION_TOKEN}_static_binaries_linux.tar.gz" -D /tmp + mkdir -p "${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}/gcc_64" + tar xf "/tmp/qt6_${QT_VERSION_TOKEN}_static_binaries_linux.tar.gz" -C "${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}/gcc_64" + + - name: Download Eigen package + env: + GH_TOKEN: ${{ secrets.GH_PAT || secrets.GITHUB_TOKEN }} + run: | + ./scripts/ci/download_toolchain.sh \ + --kind eigen \ + --version "$EIGEN_VERSION" \ + --output-dir "$GITHUB_WORKSPACE/src/external/eigen" + + - name: Download ONNX Runtime (WASM) + env: + GH_TOKEN: ${{ secrets.GH_PAT || secrets.GITHUB_TOKEN }} + run: | + ./scripts/ci/download_toolchain.sh \ + --kind onnxruntime \ + --version "$ONNXRUNTIME_VERSION" \ + --platform wasm \ + --output-dir "$GITHUB_WORKSPACE/src/external/onnxruntime" + + - name: Clone Skigen + run: ./scripts/ci/clone_skigen.sh + + - name: Build WASM + run: | + source ../emsdk/emsdk_env.sh + ./scripts/wasm/wasm.sh --emsdk 4.0.7 + + - name: Prepare WASM artifacts + run: | + rm -rf out/wasm/bin/mne_analyze_plugins + rm -rf resources/data + cp resources/design/logos/qtlogo.svg out/wasm/bin/qtlogo.svg + if [ -d "out/wasm/examples" ]; then + cp resources/design/logos/qtlogo.svg out/wasm/examples/qtlogo.svg + fi + # Replace bare Qt HTML with branded loading screens & inject COOP/COEP SW + ./scripts/wasm/wasm_postbuild.sh out/wasm/bin + if [ -d "out/wasm/examples" ]; then + ./scripts/wasm/wasm_postbuild.sh out/wasm/examples + fi + + - name: Upload WASM build + if: inputs.upload_artifact + uses: actions/upload-artifact@v7 + with: + name: wasm-build + path: out/wasm + retention-days: 1 diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 9402b9df0a..d0af876280 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -5,13 +5,17 @@ name: "CodeQL" +# Not run on pushes to staging: the shared mne-tools runner pool cannot absorb +# an analysis per push, and the weekly schedule covers staging. The analysis +# keeps a real build so moc/uic output and template instantiations are seen. on: push: - branches: [ "main", "staging" ] + branches: [ "main" ] pull_request: branches: [ "main" ] schedule: - cron: '28 15 * * 1' + workflow_dispatch: concurrency: group: codeql-${{ github.ref }} @@ -83,6 +87,7 @@ jobs: uses: github/codeql-action/init@v4 with: languages: ${{ matrix.language }} + build-mode: manual # Disable CodeQL TRAP caching: each cache entry is ~3.7 GB and two of # them (~7.4 GB) dominate the repo's 10 GB Actions cache budget, evicting # the Qt/sample-data caches via LRU and forcing unnecessary re-downloads. @@ -100,7 +105,7 @@ jobs: - name: Configure and compile MNE-CPP run: | cmake -B build -S . -DCMAKE_BUILD_TYPE=Release - cmake --build build + cmake --build build --parallel "$(nproc)" - name: Perform CodeQL Analysis uses: github/codeql-action/analyze@v4 diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index aa9363ee4e..fe199e6e3b 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -9,9 +9,9 @@ # Triggered on pull requests targeting `staging` or `main`. # # This is the FEATURE BRANCH pipeline: -# • Verifies the project builds across all platforms -# • Tests min + max supported Qt versions -# • Runs the full test suite (without coverage — that's done on staging) +# • Runs the full test suite on all platforms with the maximum supported Qt +# (without coverage — that's done on staging) +# • Runs it with the minimum supported Qt on Linux # • No deployments, no releases # # Branch model: Feature → Staging → Main @@ -34,17 +34,10 @@ env: jobs: - # ── Build compatibility: minimum supported Qt ──────────────────────────── - BuildMinQt: - uses: ./.github/workflows/_reusable-build.yml - with: - qt_version: min - - # ── Build compatibility: maximum supported Qt ──────────────────────────── - BuildMaxQt: - uses: ./.github/workflows/_reusable-build.yml - with: - qt_version: max + # No separate min/max Qt build-only jobs: the test jobs compile the same tree + # with the same warnings-as-errors flags. The runner pool is shared by the + # whole mne-tools organization (and only 5 macOS jobs run at once), so + # duplicate builds delay every repository's CI. # ── Tests (no coverage collection) ────────────────────────────────────── Tests: @@ -53,10 +46,12 @@ jobs: with_code_coverage: false upload_codecov: false + # Min-Qt on Linux; release PRs into main test it on all three OSes. TestsMinQt: uses: ./.github/workflows/_reusable-tests.yml with: qt_version: min + os_json: ${{ github.base_ref == 'main' && '["ubuntu-24.04", "macos-26", "windows-2025-vs2026"]' || '["ubuntu-24.04"]' }} # ── Quality gates (static, no build) ──────────────────────────────────── Quality: @@ -123,3 +118,8 @@ jobs: channel: stable secrets: inherit + # ── WebAssembly build (Linux only, no deployment) ─────────────────────── + WasmBuild: + uses: ./.github/workflows/_reusable-wasm.yml + secrets: inherit + diff --git a/.github/workflows/staging.yml b/.github/workflows/staging.yml index 0541cdb9d8..aef6d1d086 100644 --- a/.github/workflows/staging.yml +++ b/.github/workflows/staging.yml @@ -6,7 +6,15 @@ # Staging Branch Pipeline # ═══════════════════════════════════════════════════════════════════════════ # -# Triggered on pushes to `staging`. +# Every push to `staging` runs the quality and docs gates, all tests (three +# OSes, minimum and maximum Qt) and the WebAssembly build. The release builds, +# installers and deployments (including the WebAssembly one) run nightly (only when `staging` moved since the last +# nightly), on manual dispatch, and after a push that changed the build or +# packaging since the last dev build, as a separate run that later pushes do +# not cancel. They only start once staging compiles. The mne-tools runner pool +# is shared by the whole organization, so they are skipped where a push cannot +# affect them. +# A failing nightly opens an issue, which closes when a nightly passes again. # # This is the DEVELOPMENT pipeline: # • Creates/updates a rolling "dev_build" pre-release on GitHub @@ -31,11 +39,23 @@ on: push: branches: - staging - -# Cancel superseded runs + schedule: + # 01:13 UTC: over Sep–Oct 2026 the mne-tools runner pool was quietest from + # about 01:00 to 04:00 UTC (MNE-Python, MNE-BIDS and MNE-BIDS-Pipeline CI + # all near idle), and staging pushes usually start around 07:00 UTC. The + # tests take ~1.5 h, so the release-build burst lands around 02:45–04:15. + - cron: '13 1 * * *' + workflow_dispatch: + inputs: + release_only: + description: "Skip the tests (a push already compiled this commit) and only build and publish releases" + type: boolean + default: false + +# Cancel superseded push runs; a push never cancels a nightly or manual run. concurrency: - group: staging-${{ github.ref }} - cancel-in-progress: true + group: staging-${{ github.event_name }}-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'push' }} permissions: contents: write @@ -48,9 +68,113 @@ env: jobs: + # ── Decide whether this run publishes dev builds ───────────────────────── + # Manual runs and a nightly with new commits do (a failed nightly is not + # retried on the same commit; its issue stays open until a later nightly + # passes). A push never does itself: if it changed the build or packaging + # since the last dev build, it hands the release to a manual run, because + # the next push would cancel the push run after dev_build was deleted. + Changes: + runs-on: ubuntu-24.04 + permissions: + actions: read + contents: read + outputs: + release: ${{ steps.check.outputs.release }} + handoff: ${{ steps.check.outputs.handoff }} + + steps: + - name: Decide whether to build releases + id: check + env: + GH_TOKEN: ${{ github.token }} + GH_REPO: ${{ github.repository }} + run: | + handoff=false + case "${{ github.event_name }}" in + workflow_dispatch) release=true ;; + push) + release=false + # Build and packaging files; tests and docs are not part of the release builds. + # Any doubt (no dev build yet, too many files to list) hands off. + handoff=true + if base=$(gh api "repos/$GH_REPO/git/ref/tags/dev_build" --jq .object.sha 2>/dev/null) && + base=$(gh api "repos/$GH_REPO/git/tags/$base" --jq .object.sha 2>/dev/null || echo "$base") && + files=$(gh api "repos/$GH_REPO/compare/$base...${{ github.sha }}" \ + --jq 'if (.files | length) < 300 then .files[].filename else "too-many" end'); then + if ! printf '%s\n' "$files" | grep -vE '^(src/testframes|doc)/' | + grep -qE '(^|/)CMakeLists\.txt$|^cmake/|^scripts/(build|ci|deploy|wasm)/|^\.github/workflows/(staging\.yml|release-[^/]*|_reusable-release[^/]*)$|^too-many$'; then + echo "No build or packaging change since the last dev build ($base)" + handoff=false + fi + fi + ;; + schedule) + last_sha=$(gh api "repos/$GH_REPO/actions/workflows/staging.yml/runs?event=schedule&branch=${{ github.ref_name }}&status=completed&per_page=1" \ + --jq '.workflow_runs[0].head_sha // ""') + if [ "$last_sha" = "${{ github.sha }}" ]; then + echo "No new commits since the last nightly ($last_sha)" + release=false + else + release=true + fi + ;; + *) release=false ;; + esac + echo "release=$release" >> "$GITHUB_OUTPUT" + echo "handoff=$handoff" >> "$GITHUB_OUTPUT" + + # ── Compile gate ────────────────────────────────────────────────────────── + # Releases start only once staging compiles on every test configuration, so a + # broken build never replaces the last good dev_build. Failing tests do not + # block it; they fail the run (and open the nightly failure issue). + Compiled: + runs-on: ubuntu-24.04 + needs: [Changes, Tests, TestsMinQt] + if: ${{ !cancelled() && !inputs.release_only && (needs.Changes.outputs.release == 'true' || needs.Changes.outputs.handoff == 'true') }} + permissions: + actions: read + + steps: + - name: Check that every test configuration compiled + env: + GH_TOKEN: ${{ github.token }} + GH_REPO: ${{ github.repository }} + run: | + gh api --paginate "repos/$GH_REPO/actions/runs/${{ github.run_id }}/attempts/${{ github.run_attempt }}/jobs?per_page=100" \ + --jq '.jobs[] | select(.name | test("^Tests(MinQt)? / ")) | + [.name, ([.steps[] | select(.name | startswith("Configure and compile MNE-CPP")) | select(.conclusion != "skipped") | .conclusion] | first // "missing")] | @tsv' \ + > compiled.tsv + cat compiled.tsv + test -s compiled.tsv + if awk -F'\t' '$2 != "success" { bad = 1 } END { exit !bad }' compiled.tsv; then + echo "::error::Not every test configuration compiled, so dev_build is left unchanged." + exit 1 + fi + + # ── Hand a push's release to a run that later pushes do not cancel ─────── + Handoff: + runs-on: ubuntu-24.04 + needs: [Changes, Compiled] + if: ${{ !cancelled() && github.event_name == 'push' && needs.Changes.outputs.handoff == 'true' && needs.Compiled.result == 'success' }} + permissions: + actions: write + + steps: + - name: Start the release run + env: + GH_TOKEN: ${{ github.token }} + GH_REPO: ${{ github.repository }} + run: gh workflow run staging.yml --ref "${{ github.ref_name }}" -f release_only=true + # ── Create / update dev_build pre-release ──────────────────────────────── + # A release-only run follows a push run that already passed the compile gate. CreateDevRelease: runs-on: ubuntu-24.04 + needs: [Changes, Compiled] + if: ${{ !cancelled() && needs.Changes.outputs.release == 'true' && (inputs.release_only || needs.Compiled.result == 'success') }} + permissions: + contents: write steps: - name: Clone repository @@ -88,57 +212,67 @@ jobs: # ── Platform release builds (parallel) ─────────────────────────────────── Linux: needs: CreateDevRelease + if: ${{ !cancelled() && needs.CreateDevRelease.result == 'success' }} uses: ./.github/workflows/release-linux.yml secrets: inherit MacOS: needs: CreateDevRelease + if: ${{ !cancelled() && needs.CreateDevRelease.result == 'success' }} uses: ./.github/workflows/release-macos.yml secrets: inherit Windows: needs: CreateDevRelease + if: ${{ !cancelled() && needs.CreateDevRelease.result == 'success' }} uses: ./.github/workflows/release-windows.yml secrets: inherit # ── Installers (after all platform builds) ───────────────────────────── Installer: needs: [Linux, MacOS, Windows] + if: ${{ !cancelled() && needs.Linux.result == 'success' && needs.MacOS.result == 'success' && needs.Windows.result == 'success' }} uses: ./.github/workflows/release-installer.yml secrets: inherit - # ── Build compatibility matrix (min + max Qt) ─────────────────────────── - BuildMinQt: - uses: ./.github/workflows/_reusable-build.yml - with: - qt_version: min - - BuildMaxQt: - uses: ./.github/workflows/_reusable-build.yml - with: - qt_version: max + # No separate min/max Qt build-only jobs here: Tests and TestsMinQt compile + # the same tree with the same warnings-as-errors flags, and the release + # builds exercise deployment. # ── Tests with coverage threshold & regression checks ──────────────────── # Coverage is only collected on Ubuntu; macOS/Windows always run without it. # Floor and regression tolerance come from tools/quality/coverage_policy.json. Tests: + if: ${{ !inputs.release_only }} uses: ./.github/workflows/_reusable-tests.yml + permissions: + contents: read + actions: write # prune superseded ccache entries with: with_code_coverage: true upload_codecov: true enforce_coverage_gate: true + save_ccache: true secrets: CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} + # Min-Qt on all three OSes, so every push and the G1 evidence cover each + # OS x Qt pair. TestsMinQt: + if: ${{ !inputs.release_only }} uses: ./.github/workflows/_reusable-tests.yml + permissions: + contents: read + actions: write # prune superseded ccache entries with: qt_version: min + save_ccache: true # ── Doxygen API documentation (dev) ────────────────────────────────────── Doxygen: runs-on: ubuntu-24.04 needs: CreateDevRelease + if: ${{ !cancelled() && needs.CreateDevRelease.result == 'success' }} steps: - name: Clone repository @@ -242,6 +376,8 @@ jobs: retention-days: 30 # ── Documentation gate (T4.4): API docs, screenshots, site build ──────── + # Runs on every push (Linux only, ~20 min): it is the docs/API gate. Only + # the Website deployment waits for the nightly. Docs: uses: ./.github/workflows/_reusable-docs.yml with: @@ -252,6 +388,7 @@ jobs: Website: runs-on: ubuntu-24.04 needs: [CreateDevRelease, Quality, Docs] + if: ${{ !cancelled() && needs.CreateDevRelease.result == 'success' && needs.Quality.result == 'success' && needs.Docs.result == 'success' }} steps: - name: Clone repository @@ -295,89 +432,25 @@ jobs: git push origin main # ── WebAssembly (dev) ──────────────────────────────────────────────────── + WasmBuild: + uses: ./.github/workflows/_reusable-wasm.yml + with: + upload_artifact: true + secrets: inherit + + # Builds on every run (WebAssembly breaks in ways no other build sees), but + # publishes only in release runs. WebAssembly: runs-on: ubuntu-24.04 - needs: CreateDevRelease + needs: [CreateDevRelease, WasmBuild] + if: ${{ !cancelled() && needs.CreateDevRelease.result == 'success' && needs.WasmBuild.result == 'success' }} steps: - - name: Clone repository - uses: actions/checkout@v5 - - - name: Install dependencies - run: | - sudo rm -f /etc/apt/sources.list.d/microsoft-*.list /etc/apt/sources.list.d/azure-*.list /etc/apt/sources.list.d/microsoft-*.sources /etc/apt/sources.list.d/azure-*.sources - sudo apt-get update -qq - sudo apt-get install -qq build-essential libgl1-mesa-dev ninja-build - - - name: Setup Emscripten - run: | - cd .. - git clone https://github.com/emscripten-core/emsdk.git - cd emsdk - ./emsdk install 4.0.7 - ./emsdk activate 4.0.7 - - - name: Load external dependency versions - shell: bash - run: ./scripts/ci/load_external_deps.sh - - - name: Download pre-built WASM Qt binaries - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - gh release download qt_binaries -p "qt6_${QT_VERSION_TOKEN}_static_binaries_wasm.tar.gz" -D /tmp - mkdir -p "${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}/wasm_multithread" - tar xf "/tmp/qt6_${QT_VERSION_TOKEN}_static_binaries_wasm.tar.gz" -C "${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}/wasm_multithread" - echo "Qt6_DIR=${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}" >> "$GITHUB_ENV" - - - name: Download host Qt binaries for cross-compilation - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - gh release download qt_binaries -p "qt6_${QT_VERSION_TOKEN}_static_binaries_linux.tar.gz" -D /tmp - mkdir -p "${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}/gcc_64" - tar xf "/tmp/qt6_${QT_VERSION_TOKEN}_static_binaries_linux.tar.gz" -C "${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}/gcc_64" - - - name: Download Eigen package - env: - GH_TOKEN: ${{ secrets.GH_PAT || secrets.GITHUB_TOKEN }} - run: | - ./scripts/ci/download_toolchain.sh \ - --kind eigen \ - --version "$EIGEN_VERSION" \ - --output-dir "$GITHUB_WORKSPACE/src/external/eigen" - - - name: Download ONNX Runtime (WASM) - env: - GH_TOKEN: ${{ secrets.GH_PAT || secrets.GITHUB_TOKEN }} - run: | - ./scripts/ci/download_toolchain.sh \ - --kind onnxruntime \ - --version "$ONNXRUNTIME_VERSION" \ - --platform wasm \ - --output-dir "$GITHUB_WORKSPACE/src/external/onnxruntime" - - - name: Clone Skigen - run: ./scripts/ci/clone_skigen.sh - - - name: Build WASM - run: | - source ../emsdk/emsdk_env.sh - ./scripts/wasm/wasm.sh --emsdk 4.0.7 - - - name: Prepare WASM artifacts - run: | - rm -rf out/wasm/bin/mne_analyze_plugins - rm -rf resources/data - cp resources/design/logos/qtlogo.svg out/wasm/bin/qtlogo.svg - if [ -d "out/wasm/examples" ]; then - cp resources/design/logos/qtlogo.svg out/wasm/examples/qtlogo.svg - fi - # Replace bare Qt HTML with branded loading screens & inject COOP/COEP SW - ./scripts/wasm/wasm_postbuild.sh out/wasm/bin - if [ -d "out/wasm/examples" ]; then - ./scripts/wasm/wasm_postbuild.sh out/wasm/examples - fi + - name: Download WASM build + uses: actions/download-artifact@v8 + with: + name: wasm-build + path: out/wasm - name: Package and upload WASM to dev_build release env: @@ -432,7 +505,42 @@ jobs: # ── Checksums and signing evidence (after every asset upload) ───────── ReleaseEvidence: needs: [Installer, Doxygen, WebAssembly] + if: ${{ !cancelled() && needs.Installer.result == 'success' && needs.Doxygen.result == 'success' && needs.WebAssembly.result == 'success' }} uses: ./.github/workflows/_reusable-release-evidence.yml with: tag: dev_build secrets: inherit + + # ── Nightly failure issue ──────────────────────────────────────────────── + # Opens (or comments on) one tracking issue when a nightly fails, and closes + # it when a later nightly passes. + NightlyStatus: + runs-on: ubuntu-24.04 + needs: [Changes, Quality, Tests, TestsMinQt, Compiled, WasmBuild, CreateDevRelease, Linux, MacOS, Windows, Installer, Doxygen, Docs, Website, WebAssembly, ReleaseEvidence] + if: always() && github.event_name == 'schedule' && needs.Changes.outputs.release == 'true' + permissions: + issues: write + + steps: + - name: Open, update or close the nightly failure issue + env: + GH_TOKEN: ${{ github.token }} + GH_REPO: ${{ github.repository }} + FAILED: ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }} + RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + run: | + title="Nightly staging build failed" + number=$(gh issue list --state open --search "\"$title\" in:title" --json number,title \ + --jq "map(select(.title == \"$title\")) | .[0].number // empty") + if [ "$FAILED" = "true" ]; then + body="The nightly staging pipeline failed on ${{ github.sha }}: $RUN_URL" + if [ -n "$number" ]; then + gh issue comment "$number" --body "$body" + else + gh issue create --title "$title" --body "$body + + This issue closes automatically when a nightly run passes again." + fi + elif [ -n "$number" ]; then + gh issue close "$number" --comment "The nightly staging pipeline passed again on ${{ github.sha }}: $RUN_URL" + fi diff --git a/doc/website/docs/development/ci-ghactions.mdx b/doc/website/docs/development/ci-ghactions.mdx index 27c629ac9a..a0d913ad9a 100644 --- a/doc/website/docs/development/ci-ghactions.mdx +++ b/doc/website/docs/development/ci-ghactions.mdx @@ -13,8 +13,8 @@ MNE-CPP's CI is organized around the [Main – Staging – Feature branch model] | Event type | Workflow Name | Workflow Script | Effect | | ---------- | ------------- | --------------- | ------ | -| Pull Requests → `staging` or `main` | `PullRequest` | [pull-request.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/pull-request.yml) | Build matrix (Qt min + max) and tests on all platforms. PR cannot be merged until all jobs pass. | -| Pushes to `staging` | `Staging` | [staging.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/staging.yml) | Dev release binaries, code coverage with threshold/regression checks, dev website + Doxygen deployment, CodeQL analysis. | +| Pull Requests → `staging` or `main` | `PullRequest` | [pull-request.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/pull-request.yml) | Build and tests on all platforms (maximum Qt), plus minimum Qt on Linux (on all platforms for PRs into `main`), and the WebAssembly build. PR cannot be merged until all jobs pass. | +| Pushes to `staging`, nightly | `Staging` | [staging.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/staging.yml) | On push: tests with code coverage threshold/regression checks on all platforms with minimum and maximum Qt, quality and documentation gates, and the WebAssembly build. On pushes that touch the build or packaging, nightly and on manual dispatch: also dev release binaries and dev website + Doxygen deployment. | | Pushes to `main` | `Main` | [main.yml](https://github.com/mne-tools/mne-cpp/blob/main/.github/workflows/main.yml) | Builds, tests, stable website + Doxygen deployment. | | Tag `v*` on `main` | `Main` (release jobs) | [main.yml](https://github.com/mne-tools/mne-cpp/blob/main/.github/workflows/main.yml) | Full stable release: platform binaries (Linux, macOS, Windows), installers, WebAssembly, Codecov upload. | | Pushes to the `wasm` branch | `WasmTest` | [wasmtest.yml](https://github.com/mne-tools/mne-cpp/blob/main/.github/workflows/wasmtest.yml) | Creates new versions of the WebAssembly capable MNE-CPP applications and makes them accessible via the repository's `gh-pages` branch. | @@ -34,25 +34,31 @@ These are called by the main pipeline workflows using `workflow_call`. ## How the Pull Request Workflow Works -When a contributor opens or updates a pull request targeting `staging` (or `main`), `pull-request.yml` runs a build-and-test matrix: +When a contributor opens or updates a pull request targeting `staging` (or `main`), `pull-request.yml` runs: -1. **Checks out** the PR branch. -2. **Builds** twice — once with the **minimum** supported Qt version and once with the **maximum** — to ensure compatibility across the supported Qt range. -3. **Runs tests** via the reusable test workflow (without coverage uploads). -4. **Builds Doxygen** documentation to verify it compiles without errors. +1. The static **quality gates**. +2. **Builds and tests** with the **maximum** supported Qt version on Linux, macOS, and Windows, and with the **minimum** supported Qt version on Linux, via the reusable test workflow (without coverage uploads). +3. **Builds the documentation** to verify it compiles without errors. +4. **Builds WebAssembly** (without deploying it). The PR cannot be merged until all matrix jobs pass. This ensures that every change is validated on Linux, macOS, and Windows before it reaches the `staging` branch. ## How the Staging Workflow Works -`staging.yml` is the active development pipeline, triggered on every push to `staging`. It: +`staging.yml` is the active development pipeline. Every push to `staging` runs: + +- The static **quality gates** +- Tests with **code coverage** on all platforms — enforcing a minimum threshold (50%) and detecting coverage regressions — plus tests against the minimum Qt version on all platforms +- The **documentation gate** (API docs, screenshots, website build) +- The **WebAssembly build** (the dev deployment waits for the release run) + +GitHub-hosted runners are shared by every repository in the `mne-tools` organization, so the release part of the pipeline runs only where it can be affected: nightly when `staging` has changed since the last nightly, on manual dispatch (**Actions → Staging → Run workflow**), and after a push that changed the build or packaging since the last dev build (a `CMakeLists.txt` or `cmake/` outside the tests, `scripts/build/`, `scripts/ci/`, `scripts/deploy/`, or the staging and release workflows). Such a push starts the release as a separate run, which later pushes do not cancel. Once every test configuration compiles (failing tests do not block it), it: - Creates or updates the **`dev_build`** pre-release on GitHub with the latest development binaries -- Builds with both minimum and maximum Qt versions -- Runs tests with **code coverage** — enforcing a minimum threshold (50%) and detecting coverage regressions - Invokes the platform-specific release workflows (`release-linux.yml`, `release-macos.yml`, `release-windows.yml`, `release-installer.yml`) to produce development binaries tagged as `dev_build` - Deploys the **dev** version of the documentation website to `/dev/` and Doxygen API docs to `/dev/` -- Runs **CodeQL** security analysis + +A failing nightly opens a "Nightly staging build failed" issue, which closes automatically when a later nightly passes. **CodeQL** security analysis, on a full build, runs weekly, on `main` and on manual dispatch (`codeql.yml`). ## How the Main / Release Workflow Works diff --git a/doc/website/docs/development/ci-releasecycle.mdx b/doc/website/docs/development/ci-releasecycle.mdx index 1d7f865a56..43d1d4b710 100644 --- a/doc/website/docs/development/ci-releasecycle.mdx +++ b/doc/website/docs/development/ci-releasecycle.mdx @@ -45,11 +45,12 @@ The `main` branch always reflects a **production-ready** state. It is updated on The `staging` branch is the active development integration branch. Feature branches are merged here via pull requests. - Every push to `staging` triggers: - - Cross-platform builds (minimum and maximum supported Qt versions) - - Unit tests with **code coverage** — threshold checks (≥ 50%) and regression detection + - Cross-platform tests with **code coverage** — threshold checks (≥ 50%) and regression detection — plus tests against the minimum supported Qt version on all platforms + - The **WebAssembly** build +- Pushes that touch the build or packaging, nightly runs (when `staging` has changed) and manual runs also produce: - A rolling **dev pre-release** (`dev_build`) with binaries for all platforms - Deployment of the **dev** version of the website (at `/dev/`) and Doxygen API docs (at `/dev/`) - - CodeQL security analysis +- CodeQL security analysis runs weekly ### Feature Branches @@ -79,7 +80,7 @@ The website and Doxygen API docs are deployed in two versions simultaneously: | Version | URL | Updated by | |---------|-----|-----------| | **Stable** | `mne-cpp.github.io` / `mne-cpp.github.io/doxygen-api` | Pushes to `main` | -| **Dev** | `mne-cpp.github.io/dev/` / `mne-cpp.github.io/doxygen-api/dev/` | Pushes to `staging` | +| **Dev** | `mne-cpp.github.io/dev/` / `mne-cpp.github.io/doxygen-api/dev/` | Nightly builds of `staging` | Both versions are served from the same repository and branch (`gh-pages`), using subdirectory isolation — stable at the root, dev under `/dev/`. A version dropdown in the website header lets users switch between stable and dev documentation. diff --git a/doc/website/docs/development/ci.mdx b/doc/website/docs/development/ci.mdx index d4f0b22cd5..ae33b1d1ba 100644 --- a/doc/website/docs/development/ci.mdx +++ b/doc/website/docs/development/ci.mdx @@ -7,7 +7,7 @@ sidebar_label: Continuous Integration Every change to MNE-CPP is automatically built, tested, and — for releases — packaged across **Windows, Linux, and macOS** before it reaches users. The CI system runs on [GitHub Actions](https://docs.github.com/en/actions) and is organized around the [Main – Staging – Feature branch model](ci-releasecycle.mdx). -Pull requests cannot be merged until all platform jobs pass. Development builds are published on every push to `staging`; stable release binaries are created when a version tag (`v*`) is pushed on `main`. +Pull requests cannot be merged until all platform jobs pass. Development builds are published from `staging` on pushes that touch the build or packaging, and nightly; stable release binaries are created when a version tag (`v*`) is pushed on `main`. ## Guides @@ -20,8 +20,9 @@ Pull requests cannot be merged until all platform jobs pass. Development builds | Branch / Event | Workflow | What Happens | |----------------|----------|--------------| -| Pull request → `staging` or `main` | `pull-request.yml` | Build matrix (Qt min + max) + tests on all platforms | -| Push to `staging` | `staging.yml` | Dev release binaries, coverage checks, dev website + Doxygen, CodeQL | +| Pull request → `staging` or `main` | `pull-request.yml` | Build + tests on all platforms (max Qt), min Qt on Linux, WebAssembly build | +| Push to `staging` | `staging.yml` | Tests with coverage checks (min + max Qt, all platforms), quality and docs gates, WebAssembly build | +| Push touching the build, nightly, manual | `staging.yml` | Also dev release binaries, dev website + Doxygen | | Push to `main` | `main.yml` | Tests, stable website + Doxygen deployment | | Tag `v*` on `main` | `main.yml` | Full stable release: platform binaries, installers, WebAssembly | | Push to `wasm` | `wasmtest.yml` | WebAssembly build deployed to GitHub Pages |