From b1b8b9e4f2407a0c5da4a870b6b746c336e53ad8 Mon Sep 17 00:00:00 2001 From: CarinaFo Date: Sat, 11 Apr 2026 16:26:21 +1000 Subject: [PATCH 1/4] 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/4] 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/4] 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/4] 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