# Contributing

> Development setup, code style, and contribution guidelines for geolith.

## Development Setup

1. **Get the source:** the repository is private; write to contact@geolith.app for access, then work in your checkout:

```bash
cd geolith
```

2. **Install prerequisites:**

- Rust 1.85+ via [rustup](https://rustup.rs)
- Protocol Buffers compiler (`protoc`)
- A small Overture Maps dataset for testing (see [Working with Overture Data](/builder/guides/overture-data))

3. **Build and test:**

```bash
cargo build
cargo test
```

## Code Style

### Formatting

All code must be formatted with `rustfmt`:

```bash
# Check formatting
cargo fmt --check

# Apply formatting
cargo fmt
```

### Linting

All code must pass `clippy` with no warnings:

```bash
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](https://www.conventionalcommits.org/) specification:

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

[optional body]

[optional footer]
```

**Types:**

| Type | Description |
| --- | --- |
| `feat` | New feature |
| `fix` | Bug fix |
| `perf` | Performance improvement |
| `refactor` | Code change that neither fixes a bug nor adds a feature |
| `docs` | Documentation only |
| `test` | Adding or correcting tests |
| `build` | Build system or dependency changes |
| `ci` | CI configuration changes |
| `chore` | Other changes that don't modify source or tests |

**Examples:**

```bash
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:**
   ```bash
   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

Write to contact@geolith.app with:

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