Skip to content

Contributing

First off, thanks for contributing! We appreciates you.

Relationship to stac-utils/rustac

stac-utils/rustac is a Rust monorepo that provides most of the functionality of this Python package. It's pretty common that a bug in rustac-py is actually a bug in rustac. Knowing which repository to work in can be a little tricky, so don't hesitate to reach out and ask.

We depend on released versions of the rustac crates, pinned in Cargo.toml. To develop against unreleased changes, add a [patch] section to .cargo/config.toml pointing at a local checkout:

[patch.crates-io]
rustac = { path = "../rustac/crates/cli" }
stac = { path = "../rustac/crates/core" }
stac-duckdb = { path = "../rustac/crates/duckdb" }
stac-io = { path = "../rustac/crates/io" }

Remove the section before opening a pull request.

Python environment

It can be a little tricky to ensure that your Python environment is always up-to-date while developing a Rust+Python project. We're still figuring out the best way, but for now, try this:

uv sync
python -m maturin_import_hook site install

This should make sure your pytest runs are picking up the latest changes to your Rust code.

Testing

We aim for comprehensive unit testing of this library. Please provide tests for any new features, or to demonstrate bugs. Draft pull requests with a failing test to demonstrate a bug are much appreciated.

Run scripts/test for the Rust unit tests, Python tests, and CLI smoke test. The runner sets PYO3_PYTHON to the active interpreter so cached builds cannot select a different Python version. It also adds that interpreter's library directory to the shared-library search paths, preserving existing paths such as DuckDB's library directory. CI keeps separate Rust caches for each Python version. To run only the Rust unit tests, set PYO3_PYTHON to the active interpreter and use uv run cargo test --release --locked --lib with Python's library directory on the shared-library search path if needed. Do not enable the extension-module feature for Rust tests: the test executable needs to link to Python.

Submitting changes

Please open a pull request with your changes -- make sure to include unit tests. Please follow standard git commit formatting (subject line 50 characters max, wrap the body at 72 characters).

We use conventional commits. Your commits do not have to but if you'd like to format them this way, we would be grateful.

If you can, use git rebase -i to create a clean, well-formatted history before opening your pull request. If you need to make changes after opening your pull request (e.g. to fix CI breakages) we will be grateful if you squash those fixes into their relevant commits.

Thanks so much!

-Pete Gadomski