Contributing

Contributing#

We welcome contributions to the LazySlide project. This document provides guidelines for contributing to the project.

Project overview#

LazySlide is a modularized and scalable whole slide image analysis toolkit. The project is structured as follows:

  • src/lazyslide: Main package code

  • tests: Test files

  • docs: Documentation

For core contributors#

Please do not commit directly to the main branch. Instead, create a new branch for your changes and submit a pull request.

Set up development environment#

We use uv to manage our development environment. Please make sure you have it installed before proceeding.

  1. Clone the repository:

    git clone https://github.com/rendeirolab/lazyslide.git
# or
gh repo clone rendeirolab/lazyslide

  2. Checkout a new branch:

    git checkout -b my-new-branch

  3. We use uv to manage our development environment:

    uv lock
uv run pre-commit install

    We use pre-commit to run code formatting and linting checks before each commit.

  4. Start an IPython/Jupyter session:

    uv run --with ipython ipython
# or
uv run --with jupyter jupyter lab

  5. Make your changes.

Testing#

LazySlide uses pytest for testing. Tests are located in the tests directory.

To run all tests:

uv run task test

To run a specific test file:

uv run python -m pytest tests/test_example.py

When adding new tests:

  1. Create a new file in the tests directory with a name starting with test_.

  2. Import pytest and the module you want to test.

  3. Write test functions with names starting with test_.

  4. Use assertions to verify expected behavior.

Code style and development guidelines#

LazySlide uses ruff for both linting and formatting. The configuration is defined in pyproject.toml and enforced through pre-commit hooks.

To format code:

uv run task fmt
# or
ruff format docs/source src/lazyslide tests

Documentation#

Documentation is built using Sphinx and is located in the docs directory.

To build the documentation:

# Build doc with cache
uv run task doc-build
# Fresh build
uv run task doc-clean-build

To serve the documentation locally:

uv run task doc-serve

This will start a local server at http://localhost:8000.

Documentation is written in reStructuredText (.rst) and Jupyter notebooks (.ipynb) using the myst-nb extension.

Submitting changes#

  1. Commit your changes and push them to your branch.

  2. Create a pull request on GitHub.

  3. Ensure all CI checks pass.

  4. Wait for a review from a maintainer.

Reporting issues#

If you encounter a bug or have a feature request, please open an issue on the GitHub repository.

When reporting a bug, please include:

  • A clear description of the issue

  • Steps to reproduce the problem

  • Expected behavior

  • Actual behavior

  • Any relevant logs or error messages

  • Your environment (OS, Python version, package versions)