-
Notifications
You must be signed in to change notification settings - Fork 28
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
f69d53d
commit 676b131
Showing
14 changed files
with
150 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
# Contribution to MNE-LSL | ||
|
||
Contribution of all sorts are the welcome in MNE-LSL. Please fork the repository | ||
and open a PR with changes applied on your fork for review. See the | ||
[contributing instructions online](https://mne.tools/mne-lsl/stable/development/contributing.html) | ||
to run the documentation build and the unit tests locally. |
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,136 @@ | ||
.. include:: ../links.inc | ||
|
||
Contribution guide | ||
================== | ||
|
||
Thanks for taking the time to contribute! MNE-LSL is an open-source project sustained | ||
mostly by volunteer effort. We welcome contributions from anyone as long as they abide | ||
by our `Code of Conduct`_. | ||
|
||
You can propose a change; a bugfix, a docstring improvement or a new feature; by | ||
following those steps: | ||
|
||
- `Fork the MNE-LSL repository`_ on GitHub | ||
- Clone your fork locally | ||
- (optional, recommended) Create a new branch for your changes | ||
- Make your changes locally and push them to your fork | ||
- `Open a pull request`_ with a clear title and description | ||
|
||
Install in editable mode | ||
------------------------ | ||
|
||
To modify MNE-LSL, it is recommended to install it in a separate environment in editable | ||
mode. This way, you can test your changes without having to reinstall the package each | ||
time. To install MNE-LSL in editable mode, run: | ||
|
||
.. code-block:: console | ||
$ pip install -e .[all] | ||
.. note:: | ||
|
||
The ``[all]`` extra installs all optional dependencies, including those required for | ||
testing and documentation. | ||
|
||
Code style | ||
---------- | ||
|
||
MNE-LSL enforces style rules which are checked by the `pre-commit`_ framework. The rules | ||
are configured in the project's ``pyproject.toml``. To install the pre-commit hooks, | ||
run: | ||
|
||
.. code-block:: console | ||
$ pre-commit install | ||
Once installed, the hooks will run automatically before each commit. If you want to | ||
manually run the hooks, you can use: | ||
|
||
.. code-block:: console | ||
$ pre-commit run --all-files | ||
.. note:: | ||
|
||
If a PR is opened with failing pre-commit checks, the CIs will attempt to fix the | ||
failures automatically with an autofix commit. | ||
|
||
Documentation | ||
------------- | ||
|
||
The documentation uses `Sphinx`_ and `numpydoc`_ to generate the HTML pages. The | ||
`numpydoc`_ convention is used. To build the documentation locally, navigate to the | ||
``doc`` directory and run: | ||
|
||
.. code-block:: console | ||
$ make html | ||
The HTML pages will be generated in the ``doc/_build/html`` directory. You can run the | ||
following command to open a browser with the documentation: | ||
|
||
.. code-block:: console | ||
$ make view | ||
Finally, building the tutorials and examples is a slow process. To skip running the | ||
examples and tutorials, run: | ||
|
||
.. code-block:: console | ||
$ make html-noplot | ||
Tests | ||
----- | ||
|
||
The unit tests are written using `pytest`_ and can be run from the root of the | ||
repository with: | ||
|
||
.. code-block:: console | ||
$ pytest mne_lsl | ||
When adding a feature or fixing a bug, it is important to write a short test to ensure | ||
that the code behaves as expected. Separate features should be tested in separate tests | ||
to help keep the test function code short and readable. Finally, a test should use short | ||
files and run as quickly as possible. Any tests that takes more than 5 seconds to run | ||
locally should be marked with the ``@pytest.mark.slow`` decorator. | ||
|
||
Tests are stored in the ``tests`` directory in each module. As much as possible, the | ||
tests within a module should not test a different module, but this is obviously not | ||
simple or mandatory as many modules require the creation of mock LSL stream to run the | ||
tests. | ||
|
||
Fixtures used in a single module should be defined within the module itself. If a | ||
fixture is used in multiple modules, it should be defined in the ``mne_lsl/conftest.py`` | ||
file. | ||
|
||
Finally, writing reliable tests with mock LSL stream or | ||
:class:`~mne_lsl.lsl.StreamInlet` and :class:`~mne_lsl.lsl.StreamOutlet` can be tricky. | ||
Here are a couple of tips to help you write reliable tests: | ||
|
||
- If you create a mock LSL stream with :class:`~mne_lsl.player.PlayerLSL`, use the | ||
fixture ``chunk_size`` which returns a large chunk size suitable for CIs. | ||
- If you need to create inlets or outlets, always close the inlets first before closing | ||
or destroying the outlets. | ||
|
||
.. note:: | ||
|
||
A :class:`~mne_lsl.stream.StreamLSL` or :class:`~mne_lsl.player.PlayerLSL` have | ||
underlying LSL inlets and outlets. Don't forget to call | ||
:meth:`mne_lsl.stream.StreamLSL.disconnect` followed by | ||
:class:`mne_lsl.player.PlayerLSL.stop` at the end of your test. | ||
|
||
- If you need to create :class:`~mne_lsl.lsl.StreamInlet` or | ||
:class:`~mne_lsl.lsl.StreamOutlet` | ||
directly, use the ``close_io`` fixture which returns a function to call at the end of | ||
your test to remove the inlets outlets. | ||
- If the objects in your test use separate threads for acquisition or processing, don't | ||
forget to include sleep periods to ensure that the threads have time to work. | ||
|
||
.. _fork the mne-lsl repository: https://github.com/mne-tools/mne-lsl/fork | ||
.. _open a pull request: https://github.com/mne-tools/mne-lsl/compare | ||
.. _numpydoc: https://numpydoc.readthedocs.io | ||
.. _pre-commit: https://pre-commit.com | ||
.. _pytest: https://docs.pytest.org | ||
.. _sphinx: https://www.sphinx-doc.org |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters