Add AGENTS.md, updated templates and a hardware-free test example

.github/workflows/compatibility.yml

@@ -1,78 +1,15 @@
+# Everything is defined once in PyMoDAQ/pymodaq_plugins_template (reusable-*.yml). The ref after @ is the branch of the PR for now: use a release tag (@v1) once it exists.
 name: Compatibility with pymodaq (latest release)
 
 on:
-  workflow_call:
-
   pull_request:
-
   push:
-    branches:
-    - '*'
+    branches: [main, master, '[0-9]*.x']
 
 concurrency:
-  # github.workflow: name of the workflow
-  # github.event.pull_request.number || github.ref: pull request number or branch name if not a pull request
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  # Cancel in-progress runs when a new workflow with the same group name is triggered
   cancel-in-progress: true
-
-jobs:
-  tests:
-    continue-on-error: true
-    strategy:
-      fail-fast: false
-      matrix:
-        os: ["ubuntu-latest", "windows-latest"]
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
-        qt-backend: ["pyqt5", "pyqt6", "pyside6"]
-    runs-on: ${{ matrix.os }}
-    env:
-      DISPLAY: ':99'
-      QT_DEBUG_PLUGINS: 1
-
-    steps:
-      - name: Set project name environment variable
-        run: |
-          echo "plugin_name=$(echo '${{ github.repository }}' | cut -d'/' -f2)" >> $GITHUB_ENV
 
-      - name: Checkout the repo
-        uses: actions/[email protected]
-
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/[email protected]
-        with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install flake8 pytest pytest-cov pytest-qt pytest-xvfb pytest-xdist setuptools wheel numpy h5py pymodaq ${{ matrix.qt-backend }}
-          pip install -e .    
-
-      # Create folder and set permissions on Ubuntu
-      - name: Create local pymodaq folder setup env (Linux)
-        if: runner.os == 'Linux'
-        run: |
-          sudo apt update
-          sudo apt install -y libxkbcommon-x11-0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-cursor0 libxcb-randr0 libxcb-render-util0 libxcb-xinerama0 libxcb-xfixes0 x11-utils libgl1 libegl1
-          export QT_DEBUG_PLUGINS=1
-          sudo mkdir -p /etc/.pymodaq
-          sudo chmod uo+rw /etc/.pymodaq
-      - name: Exporting debug variables (Windows)
-        if: runner.os == 'Windows'
-        run: |
-          set QT_DEBUG_PLUGINS=1
-
-      - name: Compatibility tests with ${{ matrix.os }} ${{ matrix.python-version }} ${{ matrix.qt-backend}}
-        run: |
-          pytest -vv -n 1 -k "test_compatibility"          
-
-      - name: Upload compatibility report
-        if: failure()
-        uses: actions/[email protected]
-        with:
-          name:  
-          path: 'import_report_tests_${{ env.plugin_name }}_None.txt'
-          if-no-files-found: error 
-
-
+jobs:
+  compatibility:
+    uses: PyMoDAQ/pymodaq_plugins_template/.github/workflows/reusable-compatibility.yml@agent-md

.github/workflows/python-publish.yml

@@ -1,40 +1,11 @@
-# This workflow will upload a Python Package using Twine when a release is created
-# For more information see: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries
-
+# Everything is defined once in PyMoDAQ/pymodaq_plugins_template (reusable-*.yml). The ref after @ is the branch of the PR for now: use a release tag (@v1) once it exists.
 name: Upload Python Package
 
 on:
   release:
     types: [created]
 
 jobs:
-  deploy:
-
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/[email protected]
-    - name: Set up Python
-      uses: actions/[email protected]
-      with:
-        python-version: '3.x'
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install hatch hatchling toml twine
-    - name: Get history and tags for SCM versioning to work
-      run: |
-        git branch
-        git fetch --prune --unshallow
-        git fetch --depth=1 origin +refs/tags/*:refs/tags/*
-        hatch version
-    - name: Build
-      run: hatch build
-    - name: Check the build
-      run: twine check dist/*
-    - name: publish
-      env:
-        HATCH_INDEX_USER: ${{ secrets.PYPI_USERNAME }}
-        HATCH_INDEX_AUTH: ${{ secrets.PYPI_PASSWORD }}
-      run: |
-        hatch publish
+  publish:
+    uses: PyMoDAQ/pymodaq_plugins_template/.github/workflows/reusable-publish.yml@agent-md
+    secrets: inherit

.github/workflows/reusable-compatibility.yml

@@ -0,0 +1,45 @@
+# Shared by all plugins: the plugin tests on the latest PyMoDAQ release over Python versions, Qt backends and OS.
+# Called from the small `compatibility.yml` of a plugin, do not copy this file into a plugin.
+name: Reusable compatibility
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    name: ${{ matrix.os }} / Python ${{ matrix.python-version }} / ${{ matrix.qt-backend }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - {os: ubuntu-latest, python-version: '3.10', qt-backend: pyqt5}
+          - {os: ubuntu-latest, python-version: '3.10', qt-backend: pyside6}
+          - {os: ubuntu-latest, python-version: '3.13', qt-backend: pyqt6}
+          - {os: ubuntu-latest, python-version: '3.13', qt-backend: pyside6}
+          - {os: windows-latest, python-version: '3.12', qt-backend: pyqt6}
+    env:
+      QT_DEBUG_PLUGINS: 1
+    steps:
+      - uses: actions/[email protected]
+      - uses: actions/[email protected]
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install system libraries for Qt
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libxkbcommon-x11-0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-cursor0 libxcb-randr0 libxcb-render-util0 libxcb-xinerama0 libxcb-xfixes0 x11-utils libgl1 libegl1
+          sudo mkdir -p /etc/.pymodaq
+          sudo chmod uo+rw /etc/.pymodaq
+      - name: Install the plugin with the latest PyMoDAQ release
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest pytest-qt pytest-xvfb ${{ matrix.qt-backend }}
+          pip install -e .
+      - name: Tests
+        run: pytest -vv tests

.github/workflows/reusable-publish.yml

@@ -0,0 +1,41 @@
+# Shared by all plugins: build the package and upload it to PyPI.
+# The repository secrets PYPI_USERNAME (`__token__`) and PYPI_PASSWORD (the PyPI API token) are passed by the caller.
+# Called from the small `python-publish.yml` of a plugin, do not copy this file into a plugin.
+name: Reusable publish
+
+on:
+  workflow_call:
+    secrets:
+      PYPI_USERNAME:
+        required: true
+      PYPI_PASSWORD:
+        required: true
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/[email protected]
+        with:
+          fetch-depth: 0  # history and tags, needed by hatch-vcs for the version
+      - uses: actions/[email protected]
+        with:
+          python-version: '3.x'
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install hatch hatchling toml twine
+      - name: Show the version
+        run: hatch version
+      - name: Build
+        run: hatch build
+      - name: Check the build
+        run: twine check dist/*
+      - name: Publish
+        env:
+          HATCH_INDEX_USER: ${{ secrets.PYPI_USERNAME }}
+          HATCH_INDEX_AUTH: ${{ secrets.PYPI_PASSWORD }}
+        run: hatch publish

.github/workflows/reusable-tests.yml

@@ -0,0 +1,44 @@
+# Shared by all plugins: flake8 gate and unit tests on one Python version and one Qt backend.
+# Called from the small `tests.yml` of a plugin, do not copy this file into a plugin.
+name: Reusable tests
+
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        type: string
+        default: '3.11'
+      qt-backend:
+        type: string
+        default: pyside6
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      QT_DEBUG_PLUGINS: 1
+    steps:
+      - uses: actions/[email protected]
+      - uses: actions/[email protected]
+        with:
+          python-version: ${{ inputs.python-version }}
+      - name: Install system libraries for Qt
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libxkbcommon-x11-0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-cursor0 libxcb-randr0 libxcb-render-util0 libxcb-xinerama0 libxcb-xfixes0 x11-utils libgl1 libegl1
+          sudo mkdir -p /etc/.pymodaq
+          sudo chmod uo+rw /etc/.pymodaq
+      - name: Install the plugin
+        run: |
+          python -m pip install --upgrade pip
+          pip install flake8 pytest pytest-qt pytest-xvfb ${{ inputs.qt-backend }}
+          pip install -e .
+      - name: Lint (syntax errors and undefined names only)
+        run: flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+      - name: Tests
+        # no xdist: parallel workers race to create the PyMoDAQ config folder on a fresh runner
+        run: pytest tests

.github/workflows/tests.yml

@@ -0,0 +1,8 @@
+# Everything is defined once in PyMoDAQ/pymodaq_plugins_template (reusable-*.yml). The ref after @ is the branch of the PR for now: use a release tag (@v1) once it exists.
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  tests:
+    uses: PyMoDAQ/pymodaq_plugins_template/.github/workflows/reusable-tests.yml@agent-md

.gitignore

@@ -114,3 +114,4 @@ venv.bak/
 
 *yacctab.py
 *lextab.py
+STATUS_AI_DEV.md