Skip to content

contributing.md

Latest commit

 

History

History
158 lines (104 loc) · 6.75 KB

contributing.md

File metadata and controls

158 lines (104 loc) · 6.75 KB
Raw

Contributing

You can contribute to NDK by creating GitHub issues or by submitting pull requests.

Reporting issues

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.

Contributing code

Standards

To ensure efficient collaborative development, a variety of standards are utilized in this project.

Preparing your environment

Start by cloning the repository:

git clone https://github.com/agencyenterprise/neurotechdevkit.git
cd neurotechdevkit

Running on docker

If you don't want to install NDK's dependencies on your machine, you can run it in a container:

  • Install Docker.

  • Run the container, which will start a jupyter notebook server:

    docker compose up

  • Connect to the jupyter notebook directly in your browser or with your IDE.

Running locally

This project requires Python >=3.9 and <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.

We use poetry to manage dependencies and virtual environments. Follow the instructions from poetry's documentation to install it if you don't have it on your system.

Install the dependencies by running the following command in a shell within the project directory:

poetry install

This will resolve and install the dependencies from poetry.lock and will install the neurotechdevkit package in editable mode.

Install stride with:

$ poetry run pip install git+https://github.com/trustimaging/stride@2520c59

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:

poetry shell

If you are already using your own virtual environment, you should not need to change anything.

Code requirements and conventions

!!! note 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:

  1. all unit and integration tests are passing: 
    make test
  2. the code is linted and formatted: 
    make lint
  3. type hinting is used on all function and method parameters and return values, excluding tests
  4. docstring usage conforms to the following:
    1. all docstrings should follow PEP257 Docstring Conventions
    2. all public API classes, functions, methods, and properties have docstrings and follow the Google Python Style Guide
    3. docstrings on private objects are not required, but are encouraged where they would significantly aid understanding
  5. testing is done using the pytest library, and test coverage should not unnecessarily decrease.

Process

Versioning

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:

  • release-patch
  • release-minor
  • release-major
  • norelease

Automatic release

Merged pull requests with one of the labels release-patch, release-minor or release-major will trigger a release job on CI.

The release job will:

  1. generate a new package version using semantic versioning provided by release on push
  2. update the pyproject.toml version using poetry
  3. commit the updated pyproject.toml file using the git-auto-commit action
  4. push the package to pypi using poetry publish
  5. 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

The examples you can find in the official documentation are python scripts executed in CI.

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:

  1. Scroll to the bottom of the page and click on the Show all checks link.
  2. Click on the details link of the Check the rendered docs here! job. ![circle-ci-rendered-docs](images/circle-ci-rendered-docs.png){ width="800" }

!!! note The 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:

gallery-link

{ width="500" } Within each example, the outputs of cells are also not properly displayed.