This is an automated email from the ASF dual-hosted git repository.
prantogg pushed a commit to branch update-docs
in repository https://gitbox.apache.org/repos/asf/sedona-spatialbench.git
The following commit(s) were added to refs/heads/update-docs by this push:
new 0d86d81 update contributors guide
0d86d81 is described below
commit 0d86d8133fe75251d08f40ff0084a9d74924bed1
Author: Pranav Toggi <[email protected]>
AuthorDate: Tue Nov 11 23:02:23 2025 -0800
update contributors guide
---
docs/contributors-guide.md | 168 +++++++++++++++++++++++++++++++++++++++------
mkdocs.yml | 1 +
2 files changed, 147 insertions(+), 22 deletions(-)
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/mkdocs.yml b/mkdocs.yml
index 92fc39b..c6defdc 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -55,6 +55,7 @@ nav:
- 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/
