Your help is welcome!

Get started contributing to zarrwhals. We assume familiarity with git and GitHub pull requests.

For more extensive tutorials, see pyOpenSci, Scientific Python, or the scanpy developer guide.

Setup¶

This project uses uv for dependency management. Optionally, mise provides task shortcuts.

uv venv -p 3.13
uv sync --all-groups

uv venv -p 3.13
mise run install

This creates a .venv with all dev, test, doc, and bench dependencies.

Code Style¶

We use prek for consistent formatting and other checks. Run checks locally:

uvx prek run --all-files

mise run check

Or run linting/formatting separately:

# Check for issues
uvx ruff check src/ tests/

# Format code
uvx ruff format src/ tests/

mise run lint
mise run format

Testing¶

We use pytest for testing.

uv run pytest tests/ -v

mise run test

With coverage:

uv run pytest tests/ --cov=zarrwhals --cov-report=html

mise run test:cov

Coverage report: htmlcov/index.html

CI¶

GitHub Actions runs tests on Python 3.11–3.13 for all PRs. A separate job tests against pre-release dependencies. See .github/workflows/test.yaml.

Documentation¶

We use MkDocs with mkdocs-shadcn, mkdocstrings, and NumPy-style docstrings.

Build:

:::bash
uv run mkdocs build

Serve with auto-reload:

:::bash
uv run mkdocs serve

Build:

:::bash
mise run docs

Serve with auto-reload:

:::bash
mise run docs:serve

Local server runs at http://127.0.0.1:8000.

Releases¶

Follow Semantic Versioning. We use uv-ship and git-cliff for automation.

# Patch release (0.0.x)
mise run release:patch

# Minor release (0.x.0)
mise run release:minor

# Major release (x.0.0)
mise run release:major

1. Update version in `pyproject.toml`
2. Generate changelog: `mise run changelog`
3. Commit changes
4. Create GitHub release with tag `vX.X.X`

GitHub releases auto-publish to PyPI.

AI Usage¶

I don't care if you use AI or not, just keep this comment in mind.