Contributor Guide#

Thank you for your interest in improving this project. This project is open-source under the Apache2.0 license and highly welcomes contributions in the form of bug reports, feature requests, and pull requests.

Here is a list of important resources for contributors:

How to report a bug#

Report bugs on the Issue Tracker.

How to request a feature#

Request features on the Issue Tracker.

Getting the code#

$ git clone --recurse-submodules https://github.com/schillerlab/sc-toolbox

How to set up your development environment#

You need Python 3.8+ and the following tools:

You can install them with:

$ pip install poetry nox nox-poetry

Install the package with development requirements:

$ make install

You can now run an interactive Python session, or the command-line interface:

$ poetry run python
$ poetry run sc_toolbox

How to test the project#

Run the full test suite:

$ nox

List the available Nox sessions:

$ nox --list-sessions

You can also run a specific Nox session. For example, invoke the unit test suite like this:

$ nox --session=tests

Unit tests are located in the tests directory, and are written using the pytest testing framework.

How to build and view the documentation#

This project uses [Sphinx] together with several extensions to build the documentation. It further requires [Pandoc] to translate various formats.

To install all required dependencies for the documentation run:

$ pip install -r docs/requirements.txt

Please note that ehrapy itself must also be installed. To build the documentation run:

$ make html

from inside the docs folder. The generated static HTML files can be found in the _build/html folder. Simply open them with your favorite browser.

How to submit changes#

Open a pull request to submit changes to this project against the development branch.

Your pull request needs to meet the following guidelines for acceptance:

  • The Nox test suite must pass without errors and warnings.

  • Include unit tests. This project maintains a high code coverage.

  • If your changes add functionality, update the documentation accordingly.

To run linting and code formatting checks before committing your change, you can install pre-commit as a Git hook by running the following command:

$ nox --session=pre-commit -- install

It is recommended to open an issue before starting work on anything. This will allow a chance to talk it over with the owners and validate your approach.