Merge pull request #57 from akhundMurad/opt/bench-speed

Add optional Rust acceleration, reproducible benchmarks, and backend-agnostic UUIDv7 handling

Author: akhundMurad

.github/workflows/ci.yml

@@ -23,6 +23,7 @@ jobs:
       - name: Sync dependencies (locked)
         run: |
           uv sync --locked --all-groups
+          uv sync --extra rust
 
       - name: Run linters
         run: |
@@ -45,6 +46,7 @@ jobs:
       - name: Sync dependencies (locked)
         run: |
           uv sync --locked --all-groups
+          uv sync --extra rust
 
       - name: Run tests
         run: |

.github/workflows/setup.yml

@@ -39,6 +39,7 @@ jobs:
       - name: Sync dependencies (locked)
         run: |
           uv sync --locked --all-groups
+          uv sync --extra rust
 
       - name: Run tests
         run: |

CONTRIBUTING.md

@@ -6,10 +6,20 @@ Thank you for taking the time to contribute ❤️
 
 ## Requirements
 
-- Linux or macOS (the development workflow is primarily tested on Unix-like systems)
-- A supported Python version (e.g. Python 3.10+; latest tested: Python 3.14)
+### Core requirements (all contributors)
+
+- Linux or macOS (development is primarily tested on Unix-like systems)
+- A supported Python version (Python **3.10+**; latest tested: **Python 3.14**)
 - [`uv`](https://astral.sh/uv/) – fast Python package manager and environment tool
 
+### Optional (for Rust acceleration work)
+
+- Rust toolchain (`rustc`, `cargo`)
+- [`maturin`](https://www.maturin.rs/) (installed automatically via `uv` if needed)
+
+> Rust is **optional**.  
+> The project must always work in pure Python mode.
+
 ## Installation
 
 ### 1. Fork & clone
@@ -20,7 +30,6 @@ Thank you for taking the time to contribute ❤️
 ```bash
 git clone https://github.com/akhundMurad/typeid-python.git
 cd typeid-python
-```
 
 ### 2. Install `uv`
 
@@ -50,6 +59,8 @@ This will:
 
 ## Running tests
 
+Run the full test suite:
+
 ```bash
 make test
 ```
@@ -60,9 +71,68 @@ or directly:
 uv run pytest -v
 ```
 
+Tests are expected to pass in **both**:
+
+- pure Python mode
+- Rust-accelerated mode (if available)
+
+## Rust acceleration (optional)
+
+TypeID includes an **optional Rust extension** used for performance-critical paths
+(e.g. base32 encode/decode).
+
+### Building the Rust extension locally
+
+If you have Rust installed:
+
+```bash
+cd rust-base32
+maturin develop
+```
+
+This installs the native extension into the active virtual environment.
+
+You can verify which backend is active via tests.
+
+### Testing Python fallback explicitly
+
+Contributors **must not break** the pure Python fallback.
+
+To test fallback behavior:
+
+```bash
+pytest tests/test_base32.py
+```
+
+This suite verifies that:
+
+- Rust is used when available
+- Python fallback is used when Rust is unavailable
+
+## Benchmarks (performance-sensitive changes)
+
+If your change affects performance-sensitive code paths (generation, parsing, base32):
+
+Run benchmarks locally:
+
+```bash
+./bench/run.sh
+```
+
+Benchmark results are:
+
+- reproducible
+- stored as raw JSON
+- compared across versions
+
+When making performance claims, include:
+
+- before/after numbers
+- raw benchmark JSON (if applicable)
+
 ## Formatters & linters
 
-We use the following tools:
+We use:
 
 - **ruff** – linting & import sorting
 - **black** – code formatting
@@ -74,7 +144,7 @@ Run all linters:
 make check-linting
 ```
 
-Auto-fix formatting issues where possible:
+Auto-fix formatting where possible:
 
 ```bash
 make fix-linting
@@ -90,6 +160,8 @@ make build
 
 This uses `uv build` under the hood.
 
+Rust wheels are built automatically in CI when applicable.
+
 ## Testing extras (CLI)
 
 To test the CLI extra locally:
@@ -102,29 +174,40 @@ uv run typeid new -p test
 ## Lockfile discipline
 
 - `uv.lock` **must be committed**
-- Always run dependency changes via `uv add` / `uv remove`
-- CI uses `uv sync --locked`, so lockfile drift will fail builds
+- Always change dependencies via `uv add` / `uv remove`
+- CI uses `uv sync --locked`
+- Lockfile drift will fail builds
 
-## How to name branches
+## Branch naming
 
 Branch names are flexible, as long as they are respectful and descriptive.
 
 Recommended patterns:
 
 - `fix/core/32`
-- `feature/cli-support`
+- `feature/rust-base32`
+- `perf/lazy-uuid`
 - `docs/readme-update`
 - `chore/ci-cleanup`
 
-Referencing an issue number in the branch name is encouraged but not required.
+Referencing an issue number is encouraged but not required.
 
 ## Submitting a Pull Request
 
 1. Create a feature branch
-2. Make sure tests and linters pass
-3. Commit with a clear message
-4. Open a pull request against `main`
-5. Describe **what** changed and **why**
+2. Ensure tests and linters pass
+3. Ensure Python fallback still works
+4. Commit with a clear message
+5. Open a pull request against `main`
+6. Describe **what** changed and **why**
+
+Performance-related PRs should explain:
+
+- which path was optimized
+- what benchmark changed
+- why the change is safe
+
+---
 
 Happy hacking 🚀
-If something is unclear, feel free to open an issue or discussion.
+If anything is unclear, feel free to open an issue or discussion.