Skip to content

Contributing to CytoScnPy

Thank you for your interest in contributing to CytoScnPy!

Prerequisites

  • Rust: Version 1.70 or higher.
  • Cargo: Comes with Rust.
  • Python: Version 3.10 or higher.
  • UV or pip: For Python dependency management.
  • Maturin: Included in the dev environment, or install manually with pip install maturin.

Setup Development Environment

  1. Fork and Clone:
git clone https://github.com/YOUR_USERNAME/cytoscnpy.git
cd cytoscnpy
  1. Create Virtual Environment:
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows
  1. Install Dependencies & Build:
uv sync --group dev --group docs
uv run maturin develop -m cytoscnpy/Cargo.toml
  1. Install the docs generator:
cargo install --locked plissken

Runs plissken render plissken.toml automatically before python -m mkdocs build or mkdocs serve, so you only need to rerun the command manually when you want to force a fresh render outside of the MkDocs lifecycle.

  1. Run Tests:
cargo test
uv run pytest python/tests
prek run --all-files

The full prek gate includes formatting/linting, Rust checks, uv lock/export hooks, strict basedpyright, and pip-audit.

Development Workflow

  1. Create a Branch: git checkout -b feature/your-feature

  2. Make Changes:

  3. Run cargo fmt to format.
  4. Run cargo clippy to lint.

  5. Run prek run --all-files before opening a PR; it includes strict basedpyright and pip-audit.

  6. Test:

  7. cargo test (Rust unit tests)

  8. uv run pytest python/tests (Python integration tests)

  9. Submit PR:

  10. Push to your fork.
  11. Open a Pull Request on GitHub.

Project Structure

  • cytoscnpy/ - Rust core library & analysis engine.
  • python/ - Python wrapper & CLI entry point.
  • editors/vscode/ - VS Code extension.
  • cytoscnpy-mcp/ - MCP server implementation.

Testing

We have a comprehensive test suite.

# Run all Rust tests
cargo test

# Run specific test
cargo test test_name

See tests/README.md for detailed testing guide.