Merge branch 'main' into doc-ref-channel-clarification

Author: Dpereaptkhamur-13

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,9 +1,23 @@
 <!--
 
-Thanks for contributing a pull request! Please make sure you have read the
-[contribution guidelines](https://mne.tools/dev/development/contributing.html)
+Thanks for contributing a pull request! Please make sure you have read
+[CONTRIBUTING.md](https://github.com/mne-tools/mne-python/blob/main/CONTRIBUTING.md)
+and the [detailed contribution guidelines](https://mne.tools/dev/development/contributing.html)
 before submitting.
 
+If you used AI to help prepare this pull request, please pay special attention to
+our **Policy on AI Assistance in Contributions** in
+[CONTRIBUTING.md](https://github.com/mne-tools/mne-python/blob/main/CONTRIBUTING.md).
+Here are some examples of what we expect for "tool, manner, and scope" disclosure:
+
+- "I implemented the code changes myself, and Claude Sonnet 4.6 wrote the test."
+- "I prompted Gemini 3.1 Pro to get a first draft implementation, then refined it
+  manually until I was satisfied."
+- "I wrote the code and asked Kimi K2.5 to write the docstring for me."
+- "I fed GPT 5.4 the paper where the algorithm is described, and asked it to implement
+  it for me. Then I had it write an example script using the `sample` dataset, and I
+  wrote the narrative text of the tutorial myself."
+
 Please be aware that we are a loose team of volunteers so patience is
 necessary. Assistance handling other issues is very welcome. We value
 all user contributions, no matter how minor they are. If we are slow to

.github/workflows/tests.yml

@@ -30,7 +30,7 @@ jobs:
           persist-credentials: false
       - uses: actions/setup-python@v6
         with:
-          python-version: '3.13'
+          python-version: '3.14'
       - uses: pre-commit/action@v3.0.1
       - run: pip install mypy numpy scipy vulture
       - run: mypy
@@ -76,15 +76,12 @@ jobs:
           - os: ubuntu-latest
             python: '3.13'
             kind: conda
-          - os: macos-latest  # arm64 (Apple Silicon): Sequoia
-            python: '3.13'
-            kind: mamba
-          - os: macos-15-intel  # intel: Sequoia
+          - os: macos-latest  # arm64
+            python: '3.14'
+            kind: pip
+          - os: macos-15-intel  # Intel
             python: '3.13'
-            kind: mamba
-          - os: windows-latest
-            python: '3.11'
-            kind: mamba
+            kind: pip
           - os: ubuntu-latest
             python: '3.12'
             kind: minimal
@@ -122,36 +119,21 @@ jobs:
       - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python }}
-        if: startswith(matrix.kind, 'pip')
+        if: startswith(matrix.kind, 'pip') || matrix.kind == 'minimal'
+        id: setup-python
+      # Workaround macOS path behavior with login shells (which puts system Python first)
+      - run: echo "export PATH=\"$(dirname ${{ steps.setup-python.outputs.python-path }}):$PATH\"" | tee -a ~/.bash_profile  # zizmor: ignore[template-injection]
+        if: startswith(matrix.kind, 'pip') && startswith(matrix.os, 'macos')
       # Python (if conda)
-      - name: Fixes for conda
-        run: |
-          # For some reason on Linux we get crashes
-          if [[ "$RUNNER_OS" == "Linux" ]]; then
-            sed -i "/numba/d" environment.yml
-          fi
-          # And on Windows and macOS PySide6.9.0 segfaults
-          if [[ "$RUNNER_OS" == "macOS" ]]; then
-            sed -i "" "s/  - PySide6 .*/  - PySide6 =6.9.2/g" environment.yml
-            sed -i "" "s/  - vtk .*/  - vtk =9.5.1/g" environment.yml
-
-          else
-            sed -i "s/  - PySide6 .*/  - PySide6 =6.9.2/g" environment.yml
-            sed -i "s/  - vtk .*/  - vtk =9.5.1/g" environment.yml
-            if [[ "$RUNNER_OS" == "Windows" ]]; then
-              echo "MNE_IS_OSMESA=true" | tee -a $GITHUB_ENV
-            fi
-          fi
-        if: matrix.kind == 'conda' || matrix.kind == 'mamba'
       - uses: mamba-org/setup-micromamba@v3
         with:
           environment-file: ${{ env.CONDA_ENV }}
           environment-name: mne
-          log-level: ${{ runner.debug == '1' && 'debug' || 'info' }}
+          log-level: 'info'
           create-args: >-
             python=${{ env.PYTHON_VERSION }}
             -v
-        if: matrix.kind == 'conda' || matrix.kind == 'mamba'
+        if: matrix.kind == 'conda'
         timeout-minutes: 20
       # Python (if old)
       - uses: astral-sh/setup-uv@v8.1.0
@@ -162,7 +144,9 @@ jobs:
             **/pylock.ci-old.toml
           python-version: ${{ matrix.python }}
         if: matrix.kind == 'old'
+      - run: bash ./tools/github_actions_verify_python.sh "${{ matrix.python }}"
       - run: bash ./tools/github_actions_dependencies.sh
+        timeout-minutes: 10
       - run: python ./tools/github_actions_check_old_env.py
         if: matrix.kind == 'old'
       # Minimal commands on Linux (macOS stalls)

CONTRIBUTING.md

@@ -7,3 +7,17 @@ Users and contributors to MNE-Python are expected to follow our [code of conduct
 
 The [contributing guide](https://mne.tools/dev/development/contributing.html) has details on the preferred contribution workflow
 and the recommended system configuration for a smooth contribution/development experience.
+
+
+Policy on AI Assistance in Contributions
+----------------------------------------
+Contributing to MNE-Python requires human judgment, contextual understanding, domain knowledge, and familiarity with MNE-Python’s structure and goals. It is not suitable for automatic processing by AI tools.
+
+You may not submit issues or pull requests generated by fully-automated tools. Maintainers reserve the right, at their sole discretion, to close such submissions and to block any account responsible for them.
+
+Review all code or documentation changes assisted by AI tools and make sure you understand all changes and can explain them on request, before submitting them under your name. Do not submit any AI-generated code that you haven’t personally reviewed, understood and tested. Please pay special attention to whether AI-assisted code reproduces specific passages for specialized algorithms, as this may risk license violations.
+
+Please do not paste AI generated text in the description of issues, PRs or in comments as this makes it harder for reviewers to assess your contribution.
+If you used AI tools, state so in your PR description and disclose the tools you have used, and the manner and scope of their assistance (see PR template for examples).
+
+PRs that appear to violate this policy will be closed without review. AI usage is an evolving issue with serious repercussions far beyond the scientific software ecosystem. The MNE-Python project reserves the right to change or reverse this policy given the developments in these areas.

azure-pipelines.yml

@@ -82,9 +82,9 @@ stages:
     variables:
       AZURE_CI: 'true'
     jobs:
-      - job: Ultraslow_PG
+      - job: Linux_Ultraslow_PG
         pool:
-          vmImage: 'ubuntu-22.04'
+          vmImage: 'ubuntu-latest'
         variables:
           DISPLAY: ':99'
           OPENBLAS_NUM_THREADS: '1'
@@ -93,7 +93,7 @@ stages:
           MNE_BROWSER_PRECOMPUTE: 'false'
         steps:
           - bash: |
-              set -e
+              set -eo pipefail
               ./tools/setup_xvfb.sh
               sudo apt install -yq tcsh
             displayName: 'Install Ubuntu dependencies'
@@ -112,19 +112,19 @@ stages:
               addToPath: true
             displayName: 'Get Python'
           - bash: |
-              set -e
+              set -eo pipefail
               python -m pip install --progress-bar off --upgrade pip
               python -m pip install --progress-bar off "mne-qt-browser[opengl] @ git+https://github.com/mne-tools/mne-qt-browser.git" pyvista scikit-learn python-picard qtpy nibabel sphinx-gallery "PySide6!=6.8.0,!=6.8.0.1,!=6.8.1.1,!=6.9.1" pandas neo pymatreader antio defusedxml curryreader pymef
               python -m pip uninstall -yq mne
               python -m pip install --progress-bar off --upgrade -e . --group=test
             displayName: 'Install dependencies with pip'
           - bash: |
-              set -e
+              set -eo pipefail
               mne sys_info -pd
               mne sys_info -pd | grep "qtpy .*(PySide6=.*)$"
             displayName: Print config
           - bash: |
-              set -e
+              set -eo pipefail
               LD_DEBUG=libs python -c "from PySide6.QtWidgets import QApplication, QWidget; app = QApplication([]); import matplotlib; matplotlib.use('QtAgg'); import matplotlib.pyplot as plt; plt.figure()"
           - bash: source tools/get_testing_version.sh
             displayName: 'Get testing version'
@@ -141,19 +141,10 @@ stages:
           - bash: bash <(curl -s https://codecov.io/bash)
             displayName: 'Codecov'
             condition: succeededOrFailed()
-          - task: PublishTestResults@2
-            inputs:
-              testResultsFiles: '**/junit-*.xml'
-              testRunTitle: 'Publish test results for $(Agent.JobName)'
-              failTaskOnFailedTests: true
-            condition: succeededOrFailed()
-          - task: PublishCodeCoverageResults@2
-            inputs:
-              summaryFileLocation: '$(System.DefaultWorkingDirectory)/**/coverage.xml'
 
-      - job: Qt
+      - job: Linux_Qt_Bindings
         pool:
-          vmImage: 'ubuntu-22.04'
+          vmImage: 'ubuntu-latest'
         variables:
           DISPLAY: ':99'
           OPENBLAS_NUM_THREADS: '1'
@@ -169,7 +160,7 @@ stages:
               addToPath: true
             displayName: 'Get Python'
           - bash: |
-              set -e
+              set -eo pipefail
               python -m pip install --progress-bar off --upgrade pip
               python -m pip install --progress-bar off --upgrade --pre --only-binary=\"numpy,scipy,matplotlib,vtk\" numpy scipy matplotlib vtk
               python -c "import vtk"
@@ -223,15 +214,6 @@ stages:
           - bash: bash <(curl -s https://codecov.io/bash)
             displayName: 'Codecov'
             condition: succeededOrFailed()
-          - task: PublishTestResults@2
-            inputs:
-              testResultsFiles: '**/junit-*.xml'
-              testRunTitle: 'Publish test results for $(Agent.JobName)'
-              failTaskOnFailedTests: true
-            condition: succeededOrFailed()
-          - task: PublishCodeCoverageResults@2
-            inputs:
-              summaryFileLocation: '$(System.DefaultWorkingDirectory)/**/coverage.xml'
 
       - job: Windows
         pool:
@@ -250,9 +232,9 @@ stages:
         strategy:
           maxParallel: 4
           matrix:
-            3.10 pip:
+            3.11 pip:
               TEST_MODE: 'pip'
-              PYTHON_VERSION: '3.10'
+              PYTHON_VERSION: '3.11'
             3.13 pip pre:
               TEST_MODE: 'pip-pre'
               PYTHON_VERSION: '3.13'
@@ -292,12 +274,3 @@ stages:
           - bash: bash <(curl -s https://codecov.io/bash)
             displayName: 'Codecov'
             condition: succeededOrFailed()
-          - task: PublishTestResults@2
-            inputs:
-              testResultsFiles: '**/junit-*.xml'
-              testRunTitle: 'Publish test results for $(Agent.JobName) $(TEST_MODE) $(PYTHON_VERSION)'
-              failTaskOnFailedTests: true
-            condition: succeededOrFailed()
-          - task: PublishCodeCoverageResults@2
-            inputs:
-              summaryFileLocation: '$(System.DefaultWorkingDirectory)/**/coverage.xml'

doc/_includes/forward.rst

@@ -689,9 +689,7 @@ EEG forward solution in the sphere model
 
     For examples of using the sphere model when computing the forward model
     (using :func:`mne.make_forward_solution`), see :ref:`Brainstorm CTF phantom
-    dataset tutorial <plt_brainstorm_phantom_ctf_eeg_sphere_geometry>`,
-    :ref:`Brainstorm Elekta phantom dataset tutorial
-    <plt_brainstorm_phantom_elekta_eeg_sphere_geometry>`, and
+    dataset tutorial <plt_brainstorm_phantom_ctf_eeg_sphere_geometry>` and
     :ref:`tut-source-alignment-without-mri`.
 
 When the sphere model is employed, the computation of the EEG solution can be

doc/changes/dev/13584.other.rst

@@ -0,0 +1 @@
+Adopting the diataxis framework by improving the phantom dipole tutorial, by `Carina Forster`_.

doc/changes/dev/13870.bugfix.rst

@@ -0,0 +1 @@
+Fix handling of optional dependencies that don't specify a version attribute, by :newcontrib:`Baris Talar`.

doc/changes/dev/13881.other.rst

@@ -0,0 +1 @@
+Fixed typos in error messages when reading measurement info, by :newcontrib:`Seth Bashford`.

doc/changes/names.inc

@@ -36,6 +36,7 @@
 .. _Asish Panda: https://github.com/kaichogami
 .. _Austin Hurst: https://github.com/a-hurst
 .. _Ayushi Satodiya: https://github.com/ayuclan
+.. _Baris Talar: https://github.com/baris-talar
 .. _Beige Jin: https://github.com/BeiGeJin
 .. _Ben Beasley: https://github.com/musicinmybrain
 .. _Benedikt Ehinger: https://www.benediktehinger.de
@@ -311,6 +312,7 @@
 .. _Sebastian Major: https://github.com/major-s
 .. _Sena Er: https://github.com/sena-neuro
 .. _Senwen Deng: https://snwn.de
+.. _Seth Bashford: https://github.com/sbashford
 .. _Seyed Yahya Shirazi: https://neuromechanist.github.io
 .. _Sheraz Khan: https://github.com/SherazKhan
 .. _Shresth Keshari: https://github.com/shresth-keshari

doc/development/contributing.rst

@@ -661,17 +661,49 @@ change, and append additional PR numbers in parentheticals with the ``:gh:`` rol
 
     Short description of the changes, by `Firstname Lastname`_. (:gh:`12346`)
 
-Test locally before opening pull requests (PRs)
------------------------------------------------
-
-MNE-Python uses `continuous integration`_ (CI) to ensure code quality and
-test across multiple installation targets. However, the CIs are often slower
-than testing locally, especially when other contributors also have open PRs
-(which is basically always the case). Therefore, do not rely on the CIs to
-catch bugs and style errors for you; :ref:`run the tests locally <run-tests>`
+Continuous integration (CI) and local testing before opening a PR
+-----------------------------------------------------------------
+
+Continuous integration (CI) uses automated systems to run tests and checks on your code
+whenever you open or update a pull request.
+MNE-Python uses `continuous integration`_ (CI) to ensure code quality,
+test across multiple platforms, and automatically validate pull requests.
+However, CI runs are slower than testing locally and some of them cost money to run.
+Therefore, *do not rely on the CIs to catch bugs and style errors for you*; 
+:ref:`run the tests locally <run-tests>`
 instead before opening a new PR and before each time you push additional
 changes to an already-open PR.
 
+MNE-Python uses the following CI services:
+
+- `GitHub Actions`_ and `Azure`_ for testing code across platforms
+- `CodeCov`_ checks how much of the code is tested
+- `CircleCI`_ for building the documentation
+
+If you are contributing for the first time, you may notice that `Github Actions`_
+jobs do not start automatically, or appear as "pending".
+This is expected behavior. Github Actions requires **manual approval from a
+maintainer** before running jobs submitted by new contributors. This is a
+security measure to prevent misuse of CI resources.
+
+As a result:
+
+- Github Actions jobs may remain in a *pending* or *not running* state
+- This does **not** indicate a problem with your code
+
+Once you have at least one PR merged into the MNE-Python repository, future
+contributions will not require manual approval.
+
+`CircleCI`_ will not build the documentation unless the GitHub account of the PR's most recent commit
+is associated with a CircleCI account. Creating one is easy and free, 
+choose "login with GitHub" on `CircleCI`_ to get started.
+If you do not do this, it will show up as a failing CI job.
+
+Before opening or updating a PR, check locally:
+
+- that all tests pass (see :ref:`run-tests`)
+- the documentation is built without errors if your changes affect it (see :ref:`build-docs`)
+- style checks pass (see :ref:`code-style`)
 
 Make tests fast and thorough
 ----------------------------
@@ -1108,11 +1140,12 @@ it can serve as a useful example of what to expect from the PR review process.
 
 .. _miniconda: https://conda.io/en/latest/miniconda.html
 .. _Spyder: https://www.spyder-ide.org/
-.. _continuous integration: https://en.wikipedia.org/wiki/Continuous_integration
+.. _continuous integration: https://about.gitlab.com/topics/ci-cd/
 .. _matplotlib: https://matplotlib.org/
 .. _github actions: https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions
 .. _azure: https://dev.azure.com/mne-tools/mne-python/_build/latest?definitionId=1&branchName=main
 .. _CircleCI: https://circleci.com/gh/mne-tools/mne-python
+.. _CodeCov: https://about.codecov.io/
 
 .. optipng