From b1b8b9e4f2407a0c5da4a870b6b746c336e53ad8 Mon Sep 17 00:00:00 2001 From: CarinaFo Date: Sat, 11 Apr 2026 16:26:21 +1000 Subject: [PATCH 1/8] add CI part --- doc/development/contributing.rst | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/doc/development/contributing.rst b/doc/development/contributing.rst index beed58f6558..5c65c89a51d 100644 --- a/doc/development/contributing.rst +++ b/doc/development/contributing.rst @@ -669,6 +669,35 @@ catch bugs and style errors for you; :ref:`run the tests locally ` instead before opening a new PR and before each time you push additional changes to an already-open PR. +Continuous integration (CI) +----------------------------------- + +MNE-Python uses `continuous integration`_ (CI) services to automatically +validate pull requests. These include: + +- `GitHub Actions`_ and `azure`_ for testing code across platforms +- `CircleCI`_ for building and validating the documentation + +If you are contributing for the first time, you may notice that `CircleCI`_ +jobs do not start automatically, or appear as "pending". + +This is expected behavior. CircleCI 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: + +- CircleCI jobs may remain in a *pending* or *not running* state +- This does **not** indicate a problem with your code + +Once a maintainer approves your pull request, CircleCI will automatically run +the documentation build and associated checks. + +In the meantime: + +- Ensure all tests pass and the docs (if relevant) are built without errors + (see :ref:`run-tests` and :ref:`build-docs`) +- Run style checks locally as described in :ref:`code-style` Make tests fast and thorough ---------------------------- From 56c3886f52a982161c27da181ea52c9064b418ff Mon Sep 17 00:00:00 2001 From: CarinaFo Date: Sat, 18 Apr 2026 13:51:26 +1000 Subject: [PATCH 2/8] clean up --- doc/development/contributing.rst | 52 +++++++++++++++++--------------- 1 file changed, 28 insertions(+), 24 deletions(-) diff --git a/doc/development/contributing.rst b/doc/development/contributing.rst index 5c65c89a51d..bdb9d77b2c2 100644 --- a/doc/development/contributing.rst +++ b/doc/development/contributing.rst @@ -658,46 +658,50 @@ 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 ` +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 ` instead before opening a new PR and before each time you push additional changes to an already-open PR. -Continuous integration (CI) ------------------------------------ +MNE-Python uses the following CI services: -MNE-Python uses `continuous integration`_ (CI) services to automatically -validate pull requests. These include: +- `GitHub Actions`_ and `Azure`_ for testing code across platforms +- `CodeCoverage`_ checks how much of the code is tested +- `CircleCI`_ for building the documentation -- `GitHub Actions`_ and `azure`_ for testing code across platforms -- `CircleCI`_ for building and validating the documentation - -If you are contributing for the first time, you may notice that `CircleCI`_ +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. CircleCI requires **manual approval from a +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: -- CircleCI jobs may remain in a *pending* or *not running* state +- Github Actions jobs may remain in a *pending* or *not running* state - This does **not** indicate a problem with your code -Once a maintainer approves your pull request, CircleCI will automatically run -the documentation build and associated checks. +Once a maintainer approves your pull request, Github Actions workflows will run. +Future contributions will not require manual approval. + +`CircleCI`_ requires to sign up for an account and link it with your github repository that you +use to contribute to MNE-Python. + +The tests will fail if you are not a registered user before you push your changes. -In the meantime: +Before opening or updating a PR, check locally: -- Ensure all tests pass and the docs (if relevant) are built without errors - (see :ref:`run-tests` and :ref:`build-docs`) -- Run style checks locally as described in :ref:`code-style` +- 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 ---------------------------- From f62251a87eb26d79cad39e6c1b00bb98f594ca8e Mon Sep 17 00:00:00 2001 From: CarinaFo Date: Sat, 18 Apr 2026 14:07:07 +1000 Subject: [PATCH 3/8] quick format --- doc/development/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/development/contributing.rst b/doc/development/contributing.rst index bdb9d77b2c2..117aae4c482 100644 --- a/doc/development/contributing.rst +++ b/doc/development/contributing.rst @@ -692,8 +692,8 @@ As a result: Once a maintainer approves your pull request, Github Actions workflows will run. Future contributions will not require manual approval. -`CircleCI`_ requires to sign up for an account and link it with your github repository that you -use to contribute to MNE-Python. +`CircleCI`_ requires to sign up for an account and link it with your github repository +that you use to contribute to MNE-Python. The tests will fail if you are not a registered user before you push your changes. From 16a6ea490172defc82d3a9f3123c2e8a00a32474 Mon Sep 17 00:00:00 2001 From: CarinaFo Date: Sat, 18 Apr 2026 15:22:29 +1000 Subject: [PATCH 4/8] added codecov link --- doc/development/contributing.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/development/contributing.rst b/doc/development/contributing.rst index 117aae4c482..8b3e83ea6d8 100644 --- a/doc/development/contributing.rst +++ b/doc/development/contributing.rst @@ -674,7 +674,7 @@ changes to an already-open PR. MNE-Python uses the following CI services: - `GitHub Actions`_ and `Azure`_ for testing code across platforms -- `CodeCoverage`_ checks how much of the code is tested +- `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`_ @@ -1138,11 +1138,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 From b756157fa51ffbc13bfb21492addb97b758ab4f7 Mon Sep 17 00:00:00 2001 From: CarinaFo Date: Sun, 26 Apr 2026 11:57:47 +1000 Subject: [PATCH 5/8] address review from Dan --- doc/development/contributing.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/doc/development/contributing.rst b/doc/development/contributing.rst index 8b3e83ea6d8..d4369be08e4 100644 --- a/doc/development/contributing.rst +++ b/doc/development/contributing.rst @@ -679,7 +679,6 @@ MNE-Python uses the following CI services: 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. @@ -689,13 +688,12 @@ 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 a maintainer approves your pull request, Github Actions workflows will run. -Future contributions will not require manual approval. - -`CircleCI`_ requires to sign up for an account and link it with your github repository -that you use to contribute to MNE-Python. +Once you have at least one PR merged into the MNE-Python repository, future +contributions will not require manual approval. -The tests will fail if you are not a registered user before you push your changes. +`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: From f608a196598ff0ab5023d790bd76458b68c0c368 Mon Sep 17 00:00:00 2001 From: CarinaFo Date: Sun, 26 Apr 2026 12:22:47 +1000 Subject: [PATCH 6/8] format --- doc/development/contributing.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/development/contributing.rst b/doc/development/contributing.rst index d4369be08e4..e0715c97834 100644 --- a/doc/development/contributing.rst +++ b/doc/development/contributing.rst @@ -692,7 +692,8 @@ 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. +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: From 410f9720b60572f5b596d1150ba2fc783bb588de Mon Sep 17 00:00:00 2001 From: CarinaFo Date: Thu, 30 Apr 2026 08:28:17 +1000 Subject: [PATCH 7/8] fix link --- doc/development/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/index.rst b/doc/development/index.rst index 98fc28f8e7f..ab097d0e8b2 100644 --- a/doc/development/index.rst +++ b/doc/development/index.rst @@ -17,7 +17,7 @@ please consider posting your questions on our `MNE Forum`_. Users and contributors to MNE-Python are expected to follow our `code of conduct`_. -The `contributing guide`_ has details on the preferred contribution workflow +The :ref:`contributing guide ` has details on the preferred contribution workflow and the recommended system configuration for a smooth contribution/development experience. From 7ff2c8835708f2f6769b502419f40fba759513da Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Wed, 29 Apr 2026 17:38:09 -0500 Subject: [PATCH 8/8] Apply suggestions from code review Co-authored-by: Daniel McCloy --- doc/development/index.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/development/index.rst b/doc/development/index.rst index ab097d0e8b2..772ac1933d5 100644 --- a/doc/development/index.rst +++ b/doc/development/index.rst @@ -17,14 +17,17 @@ please consider posting your questions on our `MNE Forum`_. Users and contributors to MNE-Python are expected to follow our `code of conduct`_. -The :ref:`contributing guide ` has details on the preferred contribution workflow +The :ref:`contributing` has details on the preferred contribution workflow and the recommended system configuration for a smooth contribution/development experience. +.. note:: + It's a good idea to always reference the version of the contributing guide `on the development version of our website`_, as this will be the most up-to-date. + .. _`opening an issue`: https://github.com/mne-tools/mne-python/issues/new/choose .. _`MNE Forum`: https://mne.discourse.group .. _`code of conduct`: https://github.com/mne-tools/.github/blob/main/CODE_OF_CONDUCT.md -.. _`contributing guide`: https://mne.tools/dev/development/contributing.html +.. _`on the development version of our website`: https://mne.tools/dev/development/contributing.html .. toctree:: :hidden: