CI.yml

name: CI
# Actions minutes are a shared, finite resource, so this workflow is
# deliberately thin. The real gate is the LOCAL suite, run before pushing
# (see CLAUDE.md "Testing policy"); CI is confirmation, not the first
# signal. Concretely: a pull request runs ONE Julia version, no docs build,
# and nothing at all for a prose-only change; the full matrix and the docs
# build run once on `main` and on tags, where the tag is actually cut.
# To get full signal on a branch without opening a pull request:
#   gh workflow run CI.yml --ref <branch>
on:
  push:
    branches:
      - main
    tags: ['*']
  pull_request:
    paths-ignore:
      - 'docs/**'
      - 'dev/**'
      - '.claude/**'
      - 'README.md'
      - 'CHANGELOG.md'
      - 'CLAUDE.md'
      - 'LICENSE'
      # NOT a blanket '**.md': test/skills.jl reads each shipped SKILL.md and
      # asserts on its frontmatter and version stamp, so a skills/*.md edit
      # really can break the suite and must still be tested.
  workflow_dispatch:
concurrency:
  # Cancel superseded runs on EVERY ref, not just pull requests: when a branch
  # gets several pushes in a row only the last one is worth building, and the
  # earlier runs are pure waste. Tags are unaffected in practice because each
  # tag is its own ref and so its own group.
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
jobs:
  test:
    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
    runs-on: ${{ matrix.os }}
    timeout-minutes: 60
    permissions: # needed to allow julia-actions/cache to proactively delete old caches that it has created
      actions: write
      contents: read
    strategy:
      fail-fast: false
      matrix:
        # A pull request runs current Julia only. The oldest supported
        # version is exercised locally before pushing and again here on
        # `main`/tags, which is where a version actually ships. Halving the
        # matrix on the branch that gets pushed most is most of the saving.
        version: ${{ github.event_name == 'pull_request' && fromJSON('["1"]') || fromJSON('["1.11", "1"]') }}
        os:
          - ubuntu-latest
        arch:
          - x64
    steps:
      - uses: actions/checkout@v6
      - uses: julia-actions/setup-julia@v3
        with:
          version: ${{ matrix.version }}
          arch: ${{ matrix.arch }}
      - uses: julia-actions/cache@v3
      # GLMakie (a hard dependency) needs an X display even to precompile,
      # so run a virtual framebuffer for the whole job.
      - name: Start virtual X display
        run: |
          sudo apt-get update
          sudo apt-get install -y xvfb
          Xvfb :99 -screen 0 1280x1024x24 &
          echo "DISPLAY=:99" >> "$GITHUB_ENV"
      - uses: julia-actions/julia-buildpkg@v1
      - uses: julia-actions/julia-runtest@v1
        with:
          prefix: xvfb-run -a
      # Coverage is computed and uploaded once, from the `main`/tag run, not
      # from every push to every branch.
      - uses: julia-actions/julia-processcoverage@v1
        if: github.event_name != 'pull_request'
      - uses: codecov/codecov-action@v6
        if: github.event_name != 'pull_request'
        with:
          files: lcov.info
  version-bumped:
    name: Version bumped
    runs-on: ubuntu-latest
    # Every pull request: ordinary work on a -DEV base keeps the version, and
    # a release-branch backport on a released base must raise it (versions.py).
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
          fetch-tags: true
      - name: Fetch base branch
        # Explicit refspec: actions/checkout's fetch config isn't guaranteed
        # to update refs/remotes/origin/<branch> for a plain `git fetch
        # origin <branch>`, and `git show origin/<base>:...` below needs it.
        run: git fetch origin "${{ github.base_ref }}:refs/remotes/origin/${{ github.base_ref }}" --depth=1
      - name: Check Project.toml version against the base branch
        # Rules (lab decision 0033) live in .github/scripts/versions.py,
        # shared with TagOnMerge.yml; its selftest runs first.
        run: |
          python3 .github/scripts/versions.py selftest
          pr_version=$(python3 .github/scripts/versions.py read < Project.toml)
          base_version=$(git show "origin/${{ github.base_ref }}:Project.toml" | python3 .github/scripts/versions.py read)

          # A release X.Y.Z, or the X.Y.Z a -DEV version leads to, must not be tagged yet.
          tag="v${pr_version%-DEV}"
          if git rev-parse -q --verify "refs/tags/$tag" >/dev/null; then
            echo "Project.toml is $pr_version but $tag is already tagged; move to the next version"
            exit 1
          fi
          python3 .github/scripts/versions.py check-pr "$pr_version" "$base_version"
  docs:
    name: Documentation
    # The longest job in this workflow by a wide margin, and it deploys
    # nothing from a pull request anyway. It runs on `main`, on tags, and on
    # demand. A docs change is checked locally with
    # `julia --project=docs docs/make.jl`.
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    permissions:
      actions: write # needed to allow julia-actions/cache to proactively delete old caches that it has created
      contents: write
      statuses: write
    steps:
      - uses: actions/checkout@v6
      - uses: julia-actions/setup-julia@v3
        with:
          version: '1'
      - uses: julia-actions/cache@v3
      - name: Start virtual X display
        run: |
          sudo apt-get update
          sudo apt-get install -y xvfb
          Xvfb :99 -screen 0 1280x1024x24 &
          echo "DISPLAY=:99" >> "$GITHUB_ENV"
      - name: Configure doc environment
        shell: julia --project=docs --color=yes {0}
        run: |
          using Pkg
          Pkg.develop(PackageSpec(path=pwd()))
          Pkg.instantiate()
      - uses: julia-actions/julia-buildpkg@v1
      # No xvfb-run prefix here: julia-docdeploy@v1 passes a multi-word prefix
      # as a single command name (exit 127). DISPLAY from the Xvfb step above
      # is enough for GLMakie.
      - uses: julia-actions/julia-docdeploy@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Run doctests
        shell: julia --project=docs --color=yes {0}
        run: |
          using Documenter: DocMeta, doctest
          using MicroscopeControl
          DocMeta.setdocmeta!(MicroscopeControl, :DocTestSetup, :(using MicroscopeControl); recursive=true)
          doctest(MicroscopeControl)