Skip to main content

Contribution Guide

MNE-CPP is an open-source project and is made better by contributions from our users. Whether you are fixing a bug, adding a new feature, or improving documentation, this guide walks you through the entire contribution workflow — from setting up your development environment to getting your code merged.

Prerequisites​

Before you begin, make sure you have:

Step-by-Step Workflow​

1. Fork and Clone​

Fork MNE-CPP's main repository to your own GitHub account, then clone it locally:

git clone https://github.com/<YourGitUserName>/mne-cpp.git
cd mne-cpp
git remote add upstream https://github.com/mne-tools/mne-cpp.git

2. Create a Feature Branch​

Always work on a dedicated branch — never commit directly to staging or main. Feature branches are created from staging, which is the active development branch:

git fetch upstream
git checkout -b my-feature upstream/staging

Choose a descriptive branch name, e.g., fix/fiff-reader-crash or feature/lsl-plugin.

3. Make Your Changes​

Implement your feature, bug fix, or documentation update. Follow the coding conventions and make sure to:

  • Use meaningful commit messages with the appropriate prefix (FIX:, ENH:, MAINT:, DOC:)
  • Document new functions with Doxygen-style comments and the @since tag
  • Make atomic commits — each commit should be a single self-contained change

4. Run Tests Locally​

Make sure your changes do not break existing functionality:

# Ensure the test data submodule is available
git submodule update --init resources/data/mne-cpp-test-data

# Build with tests enabled
cmake -B build -S . -DBUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

# Run all tests
cd build
ctest --output-on-failure

If you added new functionality, write unit tests for it. See Writing Tests for guidance.

5. Keep Your Branch Up to Date​

Regularly rebase your feature branch on the latest staging to avoid large merge conflicts:

git fetch upstream
git rebase upstream/staging

6. Push to Your Fork​

Once local tests pass, push your feature branch:

git push origin my-feature

7. Open a Pull Request​

Go to your fork on GitHub and create a pull request:

  1. Click New pull request next to the branch selector.
  2. Set the base repository to mne-tools/mne-cpp and the base branch to staging.
  3. Set the compare branch to your feature branch.
  4. Give the PR a descriptive title using the commit prefix convention (e.g., ENH: Add LSL acquisition plugin).
  5. In the description, explain what your changes do, why they are needed, and how to test them.
important

Pull requests should target the staging branch, not main. The main branch is reserved for release-ready code and is updated only by maintainers merging from staging.

For a detailed overview of how to make a pull request, see the guide on the official GitHub website.

8. Code Review and Iteration​

After you create the pull request:

  • The CI pipeline will automatically run builds and tests on all platforms.
  • MNE-CPP maintainers will review your code and may request changes.
  • Address review comments by making additional commits on your feature branch and pushing them — they are automatically added to the existing PR. There is no need to create a new pull request.
  • Once all CI checks pass and the reviewers approve, your code will be merged into staging.

9. Clean Up​

After your PR is merged, you can delete the feature branch:

git checkout staging
git branch -d my-feature
git push origin --delete my-feature

Keep your fork's staging branch up to date:

git fetch upstream
git rebase upstream/staging
git push origin staging

Tips for a Smooth Review​

  • Keep PRs focused. A PR that does one thing well is easier to review than one that mixes features, refactoring, and bug fixes.
  • Write tests. PRs with tests are reviewed faster and merged with more confidence.
  • Respond promptly. Address reviewer feedback within a few days to keep momentum.
  • Ask questions. If you are unsure about an approach, open a draft PR or start a discussion — maintainers are happy to help.