Development Setup

1. Clone the repository:

git clone https://github.com/geolith/geolith.git
cd geolith

2. Install prerequisites:

• Rust 1.85+ via rustup
• Protocol Buffers compiler (protoc)
• A small Overture Maps dataset for testing (see Working with Overture Data)

3. Build and test:

cargo build
cargo test

Code Style

Formatting

All code must be formatted with rustfmt:

# Check formatting
cargo fmt --check

# Apply formatting
cargo fmt

Linting

All code must pass clippy with no warnings:

cargo clippy -- -D warnings

Guidelines

• Use snake_case for functions and variables, PascalCase for types and traits
• Prefer returning Result<T, E> over panicking
• Use thiserror for error type definitions
• Add doc comments (///) to all public types and functions
• Keep functions focused — if a function exceeds ~50 lines, consider splitting it

Commit Message Format

Follow the Conventional Commits specification:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

Examples:

feat(layers): add land_cover layer from Overture base theme
fix(clipping): handle degenerate polygons at tile boundaries
perf(sort): reduce LZ4 chunk size for better memory usage
docs: update installation guide for Rust 1.85

Pull Request Process

1. Fork the repository and create a feature branch from main
2. Write tests for new functionality
3. Ensure all checks pass:

   cargo fmt --check
   cargo clippy -- -D warnings
   cargo test
   

4. Open a PR with a clear description of the changes
5. Respond to review feedback — maintainers may suggest changes

Adding a New Layer

To add a new layer to geolith:

1. Create a new module in src/layers/ (e.g., src/layers/my_layer.rs)
2. Implement the Layer trait:
   • Define Overture theme/type source
   • Specify required GeoParquet columns
   • Map Overture properties to protomaps attributes
   • Set min/max zoom visibility
3. Register the layer in src/layers/mod.rs
4. Add tests for property mapping
5. Update documentation

Reporting Issues

Use GitHub Issues with the appropriate template:

• Bug Report — include OS, Rust version, input data details, and error output
• Feature Request — describe the use case and expected behavior