Contributors Guide¶

This guide details how to set up your development environment as a SpatialBench contributor.

Fork and clone the repository¶

Your first step is to create a personal copy of the repository and connect it to the main project.

Fork the repository
Navigate to the official SpatialBench GitHub repository.
Click the Fork button in the top-right corner. This creates a complete copy of the project in your own GitHub account.
Clone your fork
Next, clone your newly created fork to your local machine. This command downloads the repository into a new folder named sedona-spatialbench.

Replace YourUsername with your actual GitHub username.

git clone https://github.com/YourUsername/sedona-spatialbench.git
cd sedona-spatialbench

Configure the remotes
Your local repository needs to know where the original project is so you can pull in updates. You'll add a remote link, traditionally named upstream, to the main SpatialBench repository.

Your fork is automatically configured as the origin remote.

# Add the main repository as the "upstream" remote
git remote add upstream https://github.com/apache/sedona-spatialbench.git

Verify the configuration
Run the following command to verify that you have two remotes configured correctly: origin (your fork) and upstream (the main repository).
```
git remote -v
```

The output should look like this:

origin    https://github.com/YourUsername/sedona-spatialbench.git (fetch)
origin    https://github.com/YourUsername/sedona-spatialbench.git (push)
upstream  https://github.com/apache/sedona-spatialbench.git (fetch)
upstream  https://github.com/apache/sedona-spatialbench.git (push)

Development Setup¶

SpatialBench is written in Rust and is a standard cargo workspace. You can install a recent version of the Rust compiler and cargo from rustup.rs.

To run tests:

cargo test

A local development version of the CLI can be run with:

cargo run --bin spatialbench-cli

Debugging¶

IDE¶

Debugging Rust code is most easily done by writing or finding a test that triggers the desired behavior and running it using the Debug selection in your IDE with the rust-analyzer extension.

Verbose CLI Output¶

When debugging the SpatialBench CLI, you can enable verbose output to see detailed logging:

Enable verbose output (info level logging),

cargo run --bin spatialbench-cli -- --scale-factor 1 --verbose

Or using environment variables for more granular control,

RUST_LOG=debug cargo run --bin spatialbench-cli -- --scale-factor 1

The --verbose flag sets the log level to info and ignores the RUST_LOG environment variable. When not specified, logging is configured via RUST_LOG.

Logging Levels¶

You can control logging granularity using RUST_LOG:

# Show only errors
RUST_LOG=error cargo run --bin spatialbench-cli -- --scale-factor 1

# Show warnings and errors
RUST_LOG=warn cargo run --bin spatialbench-cli -- --scale-factor 1

# Show info, warnings, and errors
RUST_LOG=info cargo run --bin spatialbench-cli -- --scale-factor 1

# Show debug output
RUST_LOG=debug cargo run --bin spatialbench-cli -- --scale-factor 1

# Show trace output (very verbose)
RUST_LOG=trace cargo run --bin spatialbench-cli -- --scale-factor 1

# Show debug output for specific modules
RUST_LOG=spatialbench=debug cargo run --bin spatialbench-cli -- --scale-factor 1

Testing¶

We use cargo to run the Rust tests:

cargo test

You can run tests for a specific crate:

cd spatialbench
cargo test

Linting¶

Install pre-commit. This will automatically run various checks (e.g., formatting) that will be needed to pass CI:

pre-commit install

Additionally, you should run clippy to catch common lints before pushing new Rust changes. This is not included in pre-commit, so this should be run manually. Fix any suggestions it makes, and run it again to make sure there are no other changes to make:

cargo clippy

Documentation¶

To contribute to the SpatialBench documentation:

Clone the repository and create a fork.
Install the Documentation dependencies:
```
pip install -r docs/requirements.txt
```
Make your changes to the documentation files.
Preview your changes locally using these commands:
mkdocs serve - Start the live-reloading docs server.
mkdocs build - Build the documentation site.
mkdocs -h - Print help message and exit.
Push your changes and open a pull request.