Contributors Guide¶

This guide details how to set up your development environment as a SedonaDB 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 Apache SedonaDB 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-db.
- Replace YourUsername with your actual GitHub username.
```
git clone https://github.com/YourUsername/sedona-db.git
cd sedona-db
```
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 Apache SedonaDB 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-db.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-db.git (fetch)
origin    https://github.com/YourUsername/sedona-db.git (push)
upstream  https://github.com/apache/sedona-db.git (fetch)
upstream  https://github.com/apache/sedona-db.git (push)

Rust¶

SedonaDB 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 and run tests using cargo test.

A local development version of the CLI can be run with cargo run --bin sedona-cli.

Test data setup¶

Some tests require submodules that contain test data or pinned versions of external dependencies. These submodules can be initialized with:

git submodule init
git submodule update --recursive

Additionally, some of the data required in the tests can be downloaded by running the following script.

python submodules/download-assets.py

System dependencies¶

Some crates wrap external native libraries and require system dependencies to build.

sedona-s2geography

At this time, the only crate that requires this is the sedona-s2geography crate, which requires CMake, Abseil and OpenSSL.

macOS¶

These can be installed on macOS with Homebrew:

brew install abseil openssl cmake geos

Linux and Windows¶

On Linux and Windows, it is recommended to use vcpkg to provide external dependencies. This can be done by setting the CMAKE_TOOLCHAIN_FILE environment variable:

export CMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake

Visual Studio Code (VSCode) Configuration¶

When using VSCode, it may be necessary to set this environment variable in settings.json such that it can be found by rust-analyzer when running build/run tasks:

{
    "rust-analyzer.runnables.extraEnv": {
        "CMAKE_TOOLCHAIN_FILE": "/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake"
    },
    "rust-analyzer.cargo.extraEnv": {
        "CMAKE_TOOLCHAIN_FILE": "/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake"
    }
}

Python¶

Python bindings to SedonaDB are built with the Maturin build backend.

To install a development version of the main Python bindings for the first time, run the following commands:

cd python/sedonadb
pip install -e ".[test]"

If editing Rust code in either SedonaDB or the Python bindings, you can recompile the native component with:

maturin develop

Debugging¶

Rust¶

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 VSCode with the rust-analyzer extension. Rust code can also be debugged using the CLI by finding the main() function in sedona-cli and choosing the Debug run option.

Python, C, and C++¶

Installation of Python bindings with maturin develop ensures a debug-friendly build for debugging Rust, Python, or C/C++ code. Python code can be debugged using breakpoints in any IDE that supports debugging an editable Python package installation (e.g., VSCode); Rust, C, or C++ code can be debugged using the CodeLLDB Attach to Process... command from the command palette in VSCode.

Low-level benchmarking¶

Low-level Rust benchmarks use criterion. In general, there is at least one benchmark for every implementation of a function (some functions have more than one implementation provided by different libraries), and a few other benchmarks for low-level iteration where work was done to optimize specific cases.

Running benchmarks¶

Benchmarks for a specific crate can be run with cargo bench:

cd rust/sedona-geo
cargo bench

Benchmarks for a specific function can be run with a filter. These can be run from the workspace or a specific crate (although the output is usually easier to read for a specific crate).

cargo bench -- st_area

Managing results¶

By default, criterion saves the last run and will report the difference between the current benchmark and the last time it was run (although there are options to save and load various baselines).

A report of the latest results for all benchmarks can be opened with the following command:

macOSUbuntu

open target/criterion/report/index.html

xdg-open target/criterion/report/index.html

All previous saved benchmark runs can be cleared with:

rm -rf target/criterion

Documentation¶

To contribute to the SedonaDB 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.