This is an automated email from the ASF dual-hosted git repository.
jiayu pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/sedona-spatialbench.git
The following commit(s) were added to refs/heads/main by this push:
new fc99f7f [DOCS] Add contributors guide and quickstart page (#61)
fc99f7f is described below
commit fc99f7f0ea0f0baead6580edf1649a6ba2d0dc93
Author: Pranav Toggi <[email protected]>
AuthorDate: Fri Nov 14 22:20:02 2025 -0800
[DOCS] Add contributors guide and quickstart page (#61)
* update contributors guide
* add quickstart.md
* fix link
* redirect to contributors_guide.md
* Apply suggestions from code review
Co-authored-by: Copilot <[email protected]>
---------
Co-authored-by: Copilot <[email protected]>
---
CONTRIBUTING.md | 56 ++++++---------
docs/contributors-guide.md | 168 +++++++++++++++++++++++++++++++++++++++------
docs/quickstart.md | 96 ++++++++++++++++++++++++++
mkdocs.yml | 2 +
4 files changed, 266 insertions(+), 56 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4d1292b..b5b1b28 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,34 +1,22 @@
-# Contributing to SpatialBench
-
-We want to make contributing to SpatialBench as easy and transparent as
-possible. If you have suggestions to improve this contribution guide, feel
-free to open an issue.
-
-## Our Development Process
-
-To contribute, please find [an existing GitHub issue or open a new
one](https://github.com/apache/sedona-spatialbench/issues). Claiming the issue
you are working on helps us better track progress.
-
-## Pull Requests
-
-We actively welcome your pull requests.
-
-1. Fork the repo and create your branch from `main`.
-2. If you've added code that should be tested, add tests.
-3. Ensure the standard tests and conformance tests are passing.
-4. Ensure your code follows Rust best practices and addresses all lints from
clippy.
-5. Open your pull request and wait for a review and approval.
-
-## Filing Issues
-
-When opening a new issue, please follow the issue template and provide as many
details
-as possible, including a reproducible example if applicable.
-
-## Coding Style
-
-Follow standard Rust formatting guidelines. For idiomatic code
-style, consult [Effective
Rust](https://www.lurklurk.org/effective-rust/title-page.html).
-
-## License
-
-By contributing to SpatialBench, you agree that your contributions will be
licensed
-under the `LICENSE` file in the root directory of this source tree.
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ -->
+
+# CONTRIBUTING.md
+
+See the [contributors-guide.md](docs/contributors-guide.md)
\ No newline at end of file
diff --git a/docs/contributors-guide.md b/docs/contributors-guide.md
index 507ba63..5f33ccf 100644
--- a/docs/contributors-guide.md
+++ b/docs/contributors-guide.md
@@ -19,36 +19,160 @@ title: Contributors Guide
under the License.
-->
-We want to make contributing to SpatialBench as easy and transparent as
-possible. If you have suggestions to improve this contribution guide, feel
-free to [open an issue in
GitHub](https://github.com/apache/sedona-spatialbench/issues).
+# Contributors Guide
-## Our Development Process
+This guide details how to set up your development environment as a
SpatialBench contributor.
-To contribute, please find an existing issue or open a new one. Claiming the
issue you are working on helps us better track progress.
+## Fork and clone the repository
-## Pull Requests
+Your first step is to create a personal copy of the repository and connect it
to the main project.
-We actively welcome your pull requests.
+1. Fork the repository
-1. Fork the repo and create your branch from `main`.
-2. If you've added code that should be tested, add tests.
-3. If you've changed APIs, update the related documentation.
-4. Ensure the standard tests and conformance tests are passing.
-5. Ensure your code follows Rust best practices and addresses all lints from
clippy.
-6. Open your pull request and wait for a review and approval.
+ * Navigate to the official [SpatialBench GitHub
repository](https://github.com/apache/sedona-spatialbench).
+ * Click the **Fork** button in the top-right corner. This creates a
complete copy of the project in your own GitHub account.
-## Filing Issues
+2. Clone your fork
-When opening a new issue, please follow the issue template and provide as many
details
-as possible, including a reproducible example if applicable.
+ * 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.
-## Coding Style
+ ```shell
+ git clone https://github.com/YourUsername/sedona-spatialbench.git
+ cd sedona-spatialbench
+ ```
-Follow standard Rust formatting guidelines. For idiomatic code
-style, consult [Effective
Rust](https://www.lurklurk.org/effective-rust/title-page.html).
+3. Configure the remotes
-## License
+ * 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.
-By contributing to SpatialBench, you agree that your contributions will be
licensed
-under the `LICENSE` file in the root directory of this source tree.
\ No newline at end of file
+ ```shell
+ # Add the main repository as the "upstream" remote
+ git remote add upstream https://github.com/apache/sedona-spatialbench.git
+ ```
+
+4. Verify the configuration
+
+ * Run the following command to verify that you have two remotes configured
correctly: origin (your fork) and upstream (the main repository).
+
+ ```shell
+ git remote -v
+ ```
+
+ * The output should look like this:
+
+ ```shell
+ 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:
+
+```shell
+cargo test
+```
+
+A local development version of the CLI can be run with:
+
+```shell
+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](https://www.jetbrains.com/help/fleet/using-rust-analyzer.html)
extension.
+
+### Verbose CLI Output
+
+When debugging the SpatialBench CLI, you can enable verbose output to see
detailed logging:
+
+Enable verbose output (info level logging),
+
+```shell
+cargo run --bin spatialbench-cli -- --scale-factor 1 --verbose
+```
+
+Or using environment variables for more granular control,
+```shell
+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`:
+
+```shell
+# 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:
+
+```shell
+cargo test
+```
+
+You can run tests for a specific crate:
+
+```shell
+cd spatialbench
+cargo test
+```
+
+## Linting
+
+Install pre-commit. This will automatically run various checks (e.g.,
formatting) that will be needed to pass CI:
+
+```shell
+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:
+
+```shell
+cargo clippy
+```
+
+## Documentation
+
+To contribute to the SpatialBench documentation:
+
+1. Clone the repository and create a fork.
+2. Install the Documentation dependencies:
+ ```shell
+ pip install -r docs/requirements.txt
+ ```
+3. Make your changes to the documentation files.
+4. 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.
+5. Push your changes and open a pull request.
\ No newline at end of file
diff --git a/docs/quickstart.md b/docs/quickstart.md
new file mode 100644
index 0000000..06d79e4
--- /dev/null
+++ b/docs/quickstart.md
@@ -0,0 +1,96 @@
+---
+title: Quickstart
+---
+
+<!---
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+## Installation
+
+Install from source:
+
+```shell
+git clone https://github.com/apache/sedona-spatialbench.git
+cd sedona-spatialbench
+cargo install --path spatialbench-cli
+```
+
+After installation, you should be able to run:
+
+```shell
+spatialbench-cli --help
+```
+
+## Generate SF1 Data
+
+To generate the full dataset at scale factor 1 in Parquet format:
+```shell
+spatialbench-cli --scale-factor 1
+```
+
+This creates six tables:
+* trip
+* customer
+* driver
+* vehicle
+* zone
+* building
+
+Output is written to the current directory by default.
+
+## Customizing Output Files
+
+We'll go over a few common options to customize the output files. To see all
available options, run `spatialbench-cli --help`.
+
+### Generate a Subset of Tables
+
+```shell
+spatialbench-cli --scale-factor 1 --tables trip,building
+```
+
+### Partition Table Output into Multiple Files
+
+Specify the number of partitions manually:
+```shell
+spatialbench-cli --scale-factor 10 --tables trip --parts 4
+```
+
+Or let the CLI determine the number of files using target size:
+```shell
+spatialbench-cli --scale-factor 10 --mb-per-file 512
+```
+
+### Set Output Directory
+
+```shell
+spatialbench-cli --scale-factor 1 --output-dir data/sf1
+```
+
+## Configuring Spatial Distributions
+
+SpatialBench uses a spatial data generator to generate synthetic points and
polygons using realistic spatial distributions.
+
+To read more about the different spatial distributions offered by SpatialBench
see [here](https://sedona.apache.org/spatialbench/spatialbench-distributions/).
+For more details about tuning the spatial distributions and the full YAML
schema and examples, see
[CONFIGURATION.md](https://github.com/apache/sedona-spatialbench/blob/main/spatialbench-cli/CONFIGURATION.md).
+
+You can override these defaults at runtime by passing a YAML file via the
`--config` flag:
+
+```shell
+spatialbench-cli --scale-factor 1 --config spatialbench-config.yml
+```
+
+If `--config` is not provided, SpatialBench checks for
./spatialbench-config.yml. If absent, it falls back to built-in defaults.
diff --git a/mkdocs.yml b/mkdocs.yml
index 92fc39b..7cfe797 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -50,11 +50,13 @@ nav:
- SedonaDB: https://sedona.apache.org/sedonadb/
- SpatialBench:
- Home: index.md
+ - Quickstart: quickstart.md
- Methodology: overview-methodology.md
- Queries: queries.md
- Datasets & Generators: datasets-generators.md
- Data Distributions: spatialbench-distributions.md
- Single Node Results: single-node-benchmarks.md
+ - Contributors Guide: contributors-guide.md
- Blog: https://sedona.apache.org/latest/blog/
- Community: https://sedona.apache.org/latest/setup/compile/
- Apache Software Foundation: https://sedona.apache.org/latest/asf/asf/
