Contributing¶

Thanks for your interest in contributing to VisCy! This page covers the whole workflow — setup, code, tests, docs, and releases.¹

Set up your environment¶

VisCy uses uv and is a uv workspace monorepo.

1. Install uv — see the installation docs.

mkdir -p /hpc/mydata/first.last/.cache/uv && ln -s /hpc/mydata/first.last/.cache/uv ~/.cache/uv

2. Get the code:

git clone https://github.com/mehta-lab/VisCy.git

3. Create the environment and sync:

cd VisCy/
uv venv -p 3.13                 # (1)!
uv sync --all-packages          # (2)!

1. VisCy targets Python ≥ 3.12.
2. Installs every workspace package plus the default dev dependency group.

Report an issue¶

We track bugs, feature requests, and support in issues. Search existing issues (including closed ones) before opening a new one.

Make changes¶

Every change to main goes through a pull request. Reference the issue it addresses, or describe the fix or feature in the PR.

Repository structure¶

viscy/
├─ pyproject.toml          # root workspace config (ruff, pytest, uv)
├─ packages/               # independently published packages
│  ├─ viscy-data/
│  ├─ viscy-models/
│  ├─ viscy-transforms/
│  └─ viscy-utils/
├─ applications/           # self-contained research apps
├─ docs/                   # this documentation site
└─ src/viscy/              # umbrella package (re-exports)

Each packages/ member is developed in isolation, published to PyPI separately, and installed on its own.

Test¶

Add tests for every code change.

uv run pytest                          # everything
uv run pytest packages/viscy-data/     # one package
uv run pytest --cov=viscy_data         # with coverage

Code style¶

We use prek to format and lint on commit. Install the hooks once:

uvx prek install
uvx prek run --all-files   # run manually

ruff handles linting and formatting; docstrings follow the numpy style.

Documentation¶

Zensical builds one site for the whole monorepo, from zensical.toml and docs/ at the repo root. Doc tools live in the root doc group.

uv sync --all-packages --group doc    # (1)!
uv run python docs/_gen_versions.py   # (2)!
uv run zensical serve                 # http://localhost:8000

uv run zensical build --clean   # output in site/ (git-ignored)

Authoring notes:

• Markdown lives in docs/; the nav table in zensical.toml sets page order.
• ::: viscy_data renders a package's API from its docstrings. A template override (docs/_templates/python/material/module.html.jinja) hides the package's top-level docstring — write overview prose in the Markdown page instead.
• zensical.toml enables only the Markdown extensions in use. Adding new syntax (math, keyboard keys, …)? Enable its extension there, or it renders as text.

Release a package¶

Publishing a GitHub Release ships that package to PyPI — no tokens, no manual upload, no version bump in code. Both the workspace libraries and the applications release this way. Versions come from the tag via uv-dynamic-versioning; the tag prefix picks the package, and each package versions independently.

Create the Release on the tag:

# standard release
gh release create viscy-data-v0.2.1 --generate-notes --title "viscy-data v0.2.1"

# pre-release (rc / alpha / beta)
gh release create viscy-data-v0.2.1rc1 --prerelease --generate-notes

Spell versions the PEP 440 way: v0.2.1, v0.2.1rc1. A misspelled or unprefixed tag fails the run before anything builds.

Before you open a PR check that:¶

• Tests cover the change and uv run pytest passes
• uvx prek run --all-files is clean
• Docs build (uv run zensical build --clean) with no warnings
• New doc pages are listed in the nav table
• The PR references an issue or describes the change