Contributing guide#

Table of Contents#

Contributing to moscot#

Clone moscot from source as:

git clone https://github.com/theislab/moscot
cd moscot
git checkout main

Install the test and development mode:

pip install -e'.[dev,test]'

Optionally install pre-commit. This will ensure that the pushed code passes the linting steps:

pre-commit install

Although the last step is not necessary, it is highly recommended, since it will help you to pass the linting step (see Code style guide). If you did install pre-commit but are unable to decipher some flags, you can still commit using the --no-verify.

Codebase structure#

The moscot project:

Tests structure:

Code style guide#

We rely on black and isort to do the most of the formatting - both of them are integrated as pre-commit hooks. You can use tox to check the changes:

tox -e lint-code

Furthermore, we also require that:

  • functions are fully type-annotated.

  • exception messages are capitalized and end with ..

  • warning messages are capitalized and do not end with ..

  • when referring to variable inside an error/warning message, enclose its name in `.

  • when referring to variable inside a docstrings, enclose its name in ``.

Testing#

We use tox to automate our testing, as well as linting and documentation creation. To run the tests, run:

tox -e py{38,39,310,311}-{linux,macos}

depending on the Python version(s) in your PATH and your operating system. We use flake8 and mypy to further analyze the code. Use # noqa: <error1>,<error2> to ignore certain flake8 errors and # type: ignore[error1,error2] to ignore specific mypy errors.

To run only a subset of tests, run:

tox -e <environment> -- <name>

where <name> can be a path to a test file/directory or a name of a test function/class. For example, to run only the tests in the plotting module, use:

tox -e py39-linux -- tests/plotting/test_plotting.py

If needed, a specific tox environment can be recreated as:

tox -e <environment> --recreate

Writing documentation#

We use numpy-style docstrings for the documentation with the following additions and modifications:

  • no type hints in the docstring (applies also for the return statement) are allowed, since all functions are required to have the type hints in their signatures.

  • when referring to some argument within the same docstring, enclose that reference in ``.

  • prefer putting references in the references.bib instead under the References sections of the docstring.

  • use docrep for repeating documentation.

In order to build the documentation, run:

tox -e build-docs

Since the tutorials are hosted on a separate repository (see Writing tutorials/examples), we download the newest tutorials/examples from there and build the documentation here.

To validate the links inside the documentation, run:

tox -e lint-docs

If you need to clean the artifacts from previous documentation builds, run:

tox -e clean-docs

Writing tutorials/examples#

Tutorials and examples are hosted on a separate repository called moscot_notebooks. Please refer to this guide for more information.

Submitting a PR#

Before submitting a new pull request, please make sure you followed these instructions:

  • make sure that you’ve branched off main and are merging into main

  • make sure that your code follows the above specified conventions (see Code style guide and Writing documentation).

  • if applicable, make sure you’ve added/modified at least 1 test to account for the changes you’ve made

  • make sure that all tests pass locally (see Testing).

  • if there is no issue which this PR solves, create a new one briefly explaining what the problem is.

  • make sure that the section under ## Description is properly formatted if automatically generating release notes, see also Creating release notes.

Making a new release#

TODO

Creating release notes#

TODO