Contributing
Thanks for your interest! Bug reports, ideas and pull requests are welcome on GitHub.
Setup
You need uv and a stable Rust toolchain.
git clone https://github.com/jeroenjanssens/polars-umap
cd polars-umap
uv sync # creates .venv and builds the extension
uv run maturin develop --uv --profile dev-release # faster rebuilds while developinguv sync builds in release mode (fat LTO), which takes a few minutes. While you iterate on the Rust code, maturin develop --profile dev-release is much faster.
Tests and linting
uv run pytest -n auto # Python tests
uv run --group parity pytest -m parity # compare with umap-learn
uv run pytest -m "slow or gpu" # larger and GPU tests
uv run pytest --doctest-modules python/polars_umap
cargo test --lib # Rust tests
uv run ruff check . && uv run ruff format --check . && uv run mypy
cargo fmt --check && cargo clippy --all-targets -- -D warningsCI runs all of these, and also tests the oldest supported Python and Polars versions.
Benchmarks
uv run --group bench python benchmarks/run.py --quick # smoke run
uv run --group bench python benchmarks/report.py # regenerate the benchmarks pageSee user_guide/benchmarks.qmd for the full methodology and the command that produced the published results.
Documentation
The site is built with Great Docs and Quarto, which you need to install separately.
bash scripts/export_notebook.sh # export the marimo notebook to WebAssembly
QUARTO_PYTHON=.venv/bin/python uv run --group docs great-docs build
uv run --group docs great-docs preview- The configuration is in
great-docs.yml. - User guide pages live in
user_guide/, examples ingallery/, and the marimo notebook innotebooks/. - The API reference is generated from the docstrings, which use the numpy style.
- Pages with Python code are executed during the build. Their outputs are cached in
_freeze/, which is committed, so CI doesn’t need to build the Rust extension. After changing a page, rebuild locally and commit the updated_freeze/. - The marimo notebook can’t run polars-umap in the browser. When you change the parameter grid, regenerate its data with
uv run python scripts/precompute_notebook_data.py.
Updating the upstream UMAP implementation
The umap and nndescent crates come from apple/embedding-atlas, pinned to a commit in Cargo.toml. To move to the latest commit and run all checks:
scripts/bump_upstream.shReleasing
- Update the version in
Cargo.tomland add an entry toCHANGELOG.md. - Commit, then tag and push:
git tag v0.2.0 && git push origin v0.2.0. - The release workflow builds the wheels, publishes them to PyPI through trusted publishing, checks that the published package installs, and creates a GitHub release.