Skip to content

Latest commit

 

History

History
197 lines (141 loc) · 8.06 KB

CONTRIBUTING.rst

File metadata and controls

197 lines (141 loc) · 8.06 KB

Contributing guide

Table of Contents

Contributing to Squidpy

Clone Squidpy from source as:

git clone https://github.com/theislab/squidpy
cd squidpy

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 in deciphering some flags, you can still commit using the --no-verify.

Codebase structure

The Squidpy project:

  • squidpy: the root of the package.
    • squidpy/gr: the graph module, which deals with building a spatial graph, running statistical tests on graphs and features etc.
    • squidpy/im: the image module, which deals with image feature calculation, cropping, etc.
    • squidpy/pl: the plotting module, which contains all the plotting functions from the graph and image modules.
    • squidpy/constants: contains internal and (possibly in the near future) external constants.

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

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{37,38,39}-{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 nhood module, use:

tox -e py38-linux -- tests/graph/test_nhood.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 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 check-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 squidpy_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 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.

Creating a new release

If you are a core developer and you want to create a new release, you need to install bump2version first as:

pip install bump2version

Depending on what part of the release you want to update, you can run:

bump2version {major,minor,patch}

By default, this will create a new tag and automatically update the __version__ wherever necessary, commit the changes and create a new tag. If you have uncommitted files in the tree, you can use --allow-dirty flag to include them in the commit.

After the version has been bumped, make sure to push the commit AND the newly create tag to the upstream. This can be done by e.g. setting push.followtags=true in your git config or use git push --atomic <branch> <tag>.

Creating release notes

By default, news fragments are automatically generated from successfully merged PRs using. Everything under ## Description section will be rendered as .rst files and automatically committed in the target branch in docs/source/release/changelog. When a new release happens, towncrier gathers all news fragments and creates the release notes under docs/source/release.

When submitting a PR, it should be tagged with one of the following tags, in order for towncrier to know under which section to render the news:

  • bugfix: the PR fixes some bug
  • feature: the PR introduces a new feature
  • deprecation: the PR deprecates something (e.g. a function)
  • doc: the PR is related to documentation
  • misc: the PR is not applicable to the above

If none is specified, bugfix is assumed. If more than 1 is specified, the first one is taken. If ignore-towncrier label is specified, no news will be generated for the PR.

To manually create news fragment, make sure that the PR doesn't generate it from the description as described above. The command to run is towncrier <PR_NUMBER>.<LABEL>, where <LABEL> is one of the labels described above. This will create a new file in the appropriate location that needs to me modified and subsequently committed.

To locally create the news fragment from an already existing PR, just run:

tox -e news -- <PR_NUMBER>

Lastly, in order to see how the current news fragments would look like in the release notes, run:

towncrier build --draft

Troubleshooting

  • The enchant C library was not found This can happen during the documentation build and because of a missing dependency for spell checker. The installation instructions for the dependency can be found here.