Contributing to MNE-Python¶

For general troubleshooting of scripts that use MNE-Python

$ git config --global user.name "Your Name"
$ git config --global user.email you@yourdomain.example.com

$ git config --global core.editor emacs    # or vim, or nano, or subl, or...

$ make

make: *** No targets specified and no makefile found.  Stop.

$ conda init bash

$ curl --remote-name https://raw.githubusercontent.com/mne-tools/mne-python/master/environment.yml
$ conda env create --file environment.yml --name mnedev
$ conda activate mnedev

$ GITHUB_USERNAME="insert_your_actual_GitHub_username_here"
$ # pick where to put your local copy of MNE-Python development version:
$ INSTALL_LOCATION="/opt"

$ cd $INSTALL_LOCATION
$ git clone https://github.com/$GITHUB_USERNAME/mne-python.git

$ cd mne-python
$ git remote add upstream git://github.com/mne-tools/mne-python.git
$ git fetch --all

$ cd $INSTALL_LOCATION/mne-python    # make sure we're in the right folder
$ pip uninstall -y mne
$ pip install -e .

$ pip install -r requirements_testing.txt

$ pip install -r requirements_doc.txt
$ conda install graphviz

$ conda install -c conda-forge sphinx-autobuild doc8

$ git checkout master            # switch to local master branch
$ git fetch upstream             # get the current state of the remote upstream repo
$ git merge upstream/master      # synchronize local master branch with remote upstream master branch
$ git checkout -b new-feature-x  # create local branch "new-feature-x" and check it out

$ git status    # see what state the local copy of the codebase is in

$ git add mne/some_file.py      # add all the changes you made to this file
$ git add mne/some_new_file.py  # add a completely new file in its entirety
$ # enter interactive staging mode, to add only portions of a file:
$ git add -p mne/viz/some_other_file.py

$ git commit -m 'ENH: adds feature X to the Epochs class'

$ git add mne/tests/some_testing_file.py
$ git commit -m 'add test of new feature X of the Epochs class'
$ git add -p mne/some_file.py mne/viz/some_other_file.py
$ git commit -m 'DOC: update Epochs and BaseEpochs docstrings'
$ git add tutorials/new_tutorial_file.py
$ git commit -m 'DOC: adds new tutorial about feature X'

$ # push local changes to remote branch origin/new-feature-x
$ # (this will create the remote branch if it doesn't already exist)
$ git push origin new-feature-x

$ git remote -v  # show existing remote addresses
$ git remote set-url origin git@github.com:$GITHUB_USERNAME/mne-python.git
$ git remote set-url upstream git@github.com:mne-tools/mne-python.git

from mne.utils import deprecated

@deprecated('my_function is deprecated and will be removed in 0.XX; please '
            'use my_new_function instead.')
def my_function():
   return 'foo'

from mne.utils import warn

def my_other_function(new_param=None, old_param=None):
    if old_param is not None:
        depr_message = ('old_param is deprecated and will be replaced by '
                        'new_param in 0.XX.')
        if new_param is None:
            new_param = old_param
            warn(depr_message, DeprecationWarning)
        else:
            warn(depr_message + ' Since you passed values for both '
                 'old_param and new_param, old_param will be ignored.',
                 DeprecationWarning)
    # Do whatever you have to do with new_param
    return 'foo'

# test deprecation warning for function
with pytest.warns(DeprecationWarning, match='my_function is deprecated'):
    my_function()

# test deprecation warning for parameter
with pytest.warns(DeprecationWarning, match='values for both old_param'):
    my_other_function(new_param=1, old_param=2)
with pytest.warns(DeprecationWarning, match='old_param is deprecated and'):
    my_other_function(old_param=2)

$ pytest --cov=mne.viz --cov-report=term-missing mne/viz/tests/test_evoked.py mne/viz/tests/test_topo.py

$ make flake

$ pytest mne/tests/test_docstring_parameters.py
$ make docstyle

$ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv > python.txt

$ make test

$ pytest mne/tests/test_evoked.py::test_io_evoked --verbose

$ pytest mne/tests/test_evoked.py -k test_io_evoked --verbose

>>> mne.datasets.testing.data_path(verbose=True)  

$ make html_dev-noplot

set PATTERN={<REGEX_TO_SELECT_MY_TUTORIAL>}
make html_dev-pattern

$ mne browse_raw ~/mne_data/MNE-sample-data/MEG/sample/sample_audvis_raw.fif

$ python -i -m mne browse_raw ...

>>> import pdb; pdb.pm()  

Contributing to MNE-Python¶

Want an example to work through?

Overview of contribution process ¶

Setting up your local environment for MNE-Python development ¶

Configuring git ¶

GNU Make ¶

Forking the MNE-Python repository ¶

Setting up the development environment ¶

Basic git commands ¶

Connecting to GitHub with SSH (optional)¶

MNE-Python coding conventions ¶

General requirements ¶

All new functionality must have test coverage¶

All new functionality must be documented¶

Avoid API changes when possible¶

Deprecate with a decorator or a warning¶

Describe your changes in the changelog¶

Test locally before opening pull requests (PRs)¶

Make tests fast and thorough¶

Code style ¶

Adhere to standard Python style guidelines¶

Use consistent variable naming¶

Follow NumPy style for docstrings¶

Cross-reference everywhere¶

Other style guidance¶

Code organization ¶

Importing¶

Return types¶

Vizualization¶

Running the test suite ¶

Building the documentation ¶

Modifying command-line tools ¶

GitHub workflow ¶