You can contribute to NDK by creating GitHub issues or by submitting pull requests.
Feel free to open an issue if you would like to discuss a new feature request or report a bug. When creating a bug report, please include as much information as possible to help us reproduce the bug as well as what the actual and expected behavior is.
To ensure efficient collaborative development, a variety of standards are utilized in this project.
- Black code formatter is used.
- Flake8 is used for linting.
- isort is used for sorting the imports.
- pyright is used for static type checking.
- Type hinting is used.
- And checked using mypy.
- Pylint is used for spell checking.
Preparing your environment
Start by cloning the repository:
Running on docker
If you don't want to install NDK's dependencies on your machine, you can run it in a container:
Run the container, which will start a jupyter notebook server:
Connect to the jupyter notebook directly in your browser or with your IDE.
This project requires Python
<3.11 to be installed. You can find the Python version you have installed by running
python --version in a terminal. If you don't have Python installed or are running an unsupported version, you can download a supported version from python.org.
Install the dependencies by running the following command in a shell within the project directory:
This will resolve and install the dependencies from
poetry.lock and will install the
neurotechdevkit package in editable mode.
Install stride with:
Follow the steps described in Setting up a compiler.
Using the environment
If you are not already using a virtual environment,
poetry will create one for you by default. You will need to use this virtual env when using or working on the package.
Activate the environment directly via:
If you are already using your own virtual environment, you should not need to change anything.
Code requirements and conventions
The following commands require
GNU make to be installed, on Windows you can install it with Chocolatey:
choco install make
Before opening a pull request, please make sure that all of the following requirements are met:
- all unit and integration tests are passing:
- the code is linted and formatted:
- type hinting is used on all function and method parameters and return values, excluding tests
- docstring usage conforms to the following:
- testing is done using the pytest library, and test coverage should not unnecessarily decrease.
NDK uses semantic versioning to identify its releases.
We use the release on push github action to generate the new version for each release. This github action generates the version based on a pull request label assigned before merge. The supported labels are:
Merged pull requests with one of the labels
release-major will trigger a release job on CI.
The release job will:
- generate a new package version using semantic versioning provided by release on push
- update the
- commit the updated
pyproject.tomlfile using the git-auto-commit action
- push the package to pypi using poetry publish
- build a new docker image and tag it with the previously generated semantic version
Pull requests merged with the tag
norelease will not trigger any of the actions listed above.
Gallery of examples
Running these scripts is a resource intensive and time consuming task, for this reason we are using CircleCI instead of Github Actions (as we can choose a more powerful machine to execute the job).
Checking NDK documentation on CI
All pull requests trigger a CI job that builds the documentation and makes the built files available.
To check the generated documentation in a pull request:
- Scroll to the bottom of the page and click on the
Show all checkslink.
- Click on the details link of the
Check the rendered docs here!job.
Examples section is not properly rendered when the documentation is built
on CI. The links of the thumbnails in
gallery/index.html point to broken paths,
in order to check one of the examples you will have to click on the left panel,
as shown in the image below:
Within each example, the outputs of cells are also not properly displayed.