Contributing Conventions — Rustic Maps SDK
The project guides set the repository’s behavioral rules. This document translates them into per-language practice, including the generated binding surfaces.
1. No abbreviations in public identifiers
Every public identifier is spelled out, and stays concise yet precise:
| Good | Bad |
|---|---|
GeographicCoordinate | GeoCoord |
RouteStep | RStep |
instruction_display_text | instrDispTxt |
fetch_traffic_incidents | fetchTI |
time_to_live_seconds | ttl |
The standard forms SDK, URL, HTTP, wasm, and MVT are accepted
in documentation text, but never as identifier shorthand.
2. SOLID mapping
| Principle | Rust core | Kotlin binding surface | Swift binding surface |
|---|---|---|---|
| Single responsibility | one crate per concern | one class per screen/feature | one struct per screen/feature |
| Open–closed | a new vendor means a new *Provider impl; the core stays untouched | a new capability means a new composable or view-model | final class + protocol; no forks in existing code |
| Liskov substitution | mocks in geospatial-traits::mock must satisfy every tested consumer | subclasses and refapps honor suspend contracts | SwiftUI view models honor async throws contracts |
| Interface segregation | ten narrow contracts, not one mega-trait | expose role-targeted protocols, not god objects | role-targeted protocols |
| Dependency inversion | crates depend on geospatial-traits, never on a provider | view models depend on injected SDK protocols | dependency injection through initializers |
3. Errors
- Rust: every failure is
geospatial_types::SDKError. Crate code uses nounwrap, noexpect, and no rawStringerrors, and panics never cross the FFI boundary. - Kotlin: UniFFI maps the UDL contract to typed exceptions, and the refapps surface them as sealed UI states.
- Swift: UniFFI maps the contract to typed Swift errors thrown from async methods.
4. Property- and fixture-first testing
- Coordinate, camera, and projection math gets
proptestsuites. - Every external payload gets a recorded fixture and a parser test.
- Reference applications double as UI-test hosts (Espresso / XCUITest / Detox).