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-db.git
The following commit(s) were added to refs/heads/main by this push:
new 6cd31c1 docs: Remove duplicate contributing guide and add a linting
section (#240)
6cd31c1 is described below
commit 6cd31c16b45aa2aa466fe33401b0f8ab34e2a8d4
Author: Peter Nguyen <[email protected]>
AuthorDate: Fri Oct 24 22:38:25 2025 -0700
docs: Remove duplicate contributing guide and add a linting section (#240)
---
CONTRIBUTING.md | 241 +--------------------------------------------
docs/contributors-guide.md | 47 ++++-----
2 files changed, 27 insertions(+), 261 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0fda9ad..7c85c85 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,243 +17,6 @@
under the License.
-->
-<!---
- 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
+# CONTRIBUTING.md
- 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.
--->
-
-# 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.
-
-1. Fork the repository
-
- * Navigate to the official [SedonaDB GitHub
repository](https://github.com/apache/sedona-db).
- * Click the **Fork** button in the top-right corner. This creates a
complete copy of the project in your own GitHub account.
-
-1. 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.
-
- ```shell
- git clone https://github.com/YourUsername/sedona-db.git
- cd sedona-db
- ```
-
-1. 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 SedonaDB repository.
- * Your fork is automatically configured as the **`origin`** remote.
-
- ```shell
- # Add the main repository as the "upstream" remote
- git remote add upstream https://github.com/apache/sedona-db.git
- ```
-
-1. 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-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](https://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:
-
-```shell
-git submodule init
-git submodule update --recursive
-```
-
-Additionally, some of the data required in the tests can be downloaded by
running the following script.
-
-```bash
-python submodules/download-assets.py
-```
-
-### System dependencies
-
-Some crates wrap external native libraries and require system dependencies
-to build.
-
-!!!note "`sedona-s2geography`"
- At this time, the only crate that requires this is the `sedona-s2geography`
- crate, which requires [CMake](https://cmake.org),
- [Abseil](https://github.com/abseil/abseil-cpp) and OpenSSL.
-
-#### macOS
-
-These can be installed on macOS with [Homebrew](https://brew.sh):
-
-```shell
-brew install abseil openssl cmake geos
-```
-
-#### Linux and Windows
-
-On Linux and Windows, it is recommended to use
[vcpkg](https://github.com/microsoft/vcpkg)
-to provide external dependencies. This can be done by setting the
`CMAKE_TOOLCHAIN_FILE`
-environment variable:
-
-```shell
-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:
-
-```json
-{
- "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](https://www.maturin.rs) build
-backend.
-
-To install a development version of the main Python bindings for the first
time, run the following commands:
-
-```shell
-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:
-
-```shell
-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](https://code.visualstudio.com/) with the
-[rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.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](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb)
-*Attach to Process...* command from the command palette in VSCode.
-
-## Low-level benchmarking
-
-Low-level Rust benchmarks use
[criterion](https://github.com/bheisler/criterion.rs).
-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`:
-
-```shell
-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).
-
-```shell
-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:
-
-=== "macOS"
- ```shell
- open target/criterion/report/index.html
- ```
-=== "Ubuntu"
- ```shell
- xdg-open target/criterion/report/index.html
- ```
-
-All previous saved benchmark runs can be cleared with:
-
-```shell
-rm -rf target/criterion
-```
-
-## Documentation
-
-To contribute to the SedonaDB documentation:
-
-1. Clone the repository and create a fork.
-1. Install the Documentation dependencies:
- ```sh
- pip install -r docs/requirements.txt
- ```
-1. Make your changes to the documentation files.
-1. 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.
-1. Push your changes and open a pull request.
+See the [contributors-guide.md](docs/contributors-guide.md)
diff --git a/docs/contributors-guide.md b/docs/contributors-guide.md
index 9f801bd..b3f3827 100644
--- a/docs/contributors-guide.md
+++ b/docs/contributors-guide.md
@@ -165,21 +165,12 @@ pip install maturin
### 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](https://code.visualstudio.com/) with the
-[rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)
-extension. Rust code can also be debugged using the CLI by finding the
`main()` function in
+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](https://code.visualstudio.com/) with the
[rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.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](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb)
-*Attach to Process...* command from the command palette in VSCode.
+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](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb)
*Attach to Process...* command from the command palette in VSCode.
## Testing
@@ -215,13 +206,29 @@ pytest python/sedonadb/tests
Remember that you need to run `maturin develop` to update your python
installation after changes in Rust code.
+## Linting
+
+Install pre-commit. This will automatically run various checks (e.g
formatting) that will be needed to pass CI.
+
+```shell
+pre-commit install
+```
+
+If pre-commit is not already installed, you can install it using pip.
+
+```shell
+pip install pre-commit
+```
+
+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
+```
+
## Low-level benchmarking
-Low-level Rust benchmarks use
[criterion](https://github.com/bheisler/criterion.rs).
-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.
+Low-level Rust benchmarks use
[criterion](https://github.com/bheisler/criterion.rs). 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
@@ -232,9 +239,7 @@ 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).
+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).
```shell
cargo bench -- st_area
@@ -242,9 +247,7 @@ 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).
+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:
