The Cardinal project adheres to the [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct). This describes the minimum behavior expected from all contributors.
## Enforcement
Instances of violations of the Code of Conduct can be reported by [contacting the lead maintainer directly](mailto:ellen.h.poe@gmail.com).
Thank you for your interest in contributing to Cardinal Maps! We would love your help. Here are some tips and guidelines for how to get started. If your quesiton isn't answered here please feel free to [open an issue](https://github.com/ellenhp/cardinal/issues/new).
## Code of Conduct
First things first, the Cardinal project adheres to the [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct). You are expected to uphold these values while participating. Please report unacceptable behavior to [the lead maintainer](mailto:ellen.h.poe@gmail.com).
## How to Contribute
### Reporting Issues
- Use the GitHub issue tracker to report bugs or suggest features
- Before creating a new issue, try to search existing issues to avoid duplicates
- Include as much relevant information as possible in your report:
- Steps to reproduce the issue
- Expected vs actual behavior
- Screenshots if applicable
- Device and OS information for Android issues
### Pull Request Process
1. Fork the repository and create your branch from `main`
2. Do your best to add some tests (at press time this is mostly aspirational)
3. Ensure your test suite passes
4. Make sure your code follows the existing style for whichever component(s) you're modifying
5. Update documentation as needed
6. Submit your pull request with a clear description of your changes
## Development Guidelines
### Android App
The Android app is built with Kotlin and follows modern Android development practices.
- Follow [Material 3 guidelines](https://m3.material.io/) for components, typography, and color schemes
- Maintain consistency in UI patterns throughout the app
- Prioritize accessibility and usability for all users
- Aim for a clean, minimalist aesthetic
#### Implementation
- Use Android Compose for all UI components
- Use Material 3 components and themes where possible
- Try to implement adaptive layouts that work across different screen sizes (currently aspirational)
- Follow the existing color scheme and typography defined in the theme
#### Building
```bash
cd cardinal-android
./gradlew assembleDebug
```
### Rust components
The offline geocoder is written in Rust and changes to it should follow Rust best practices.
#### Code Style
- Use `rustfmt` for code formatting
- Use `clippy` for linting
- Write idiomatic Rust code whenever possible
- We use UniFFI to expose rust code to Kotlin (and in the future, Swift) which imposes some limits
### Privacy and Security
- Respect user privacy in all code changes
- Avoid mistakes that could leak user data to online services without knowledge or consent (consent entails knowledge)
## Getting Help
If you need help with your contribution, feel free to:
- Ask questions in the PR comments
- Open an issue for discussion about larger changes
- Contact the maintainers directly
## Generative AI Policy
Unlike quite a few projects, we do accept contributions created with generative AI tooling with some very important caveats:
1. You must fully review all AI-generated code before submission (this should be obvious, and yet...)
2. Contributors are themselves responsible for the quality and correctness of all code, including AI-generated code they submit
3. Core business logic should not be "vibe-coded"—you may use AI for boilerplate, code review or idea generation, but not for making intricate changes to core functionality that you don't fully understand
Please see our full [Generative AI Policy](GEN_AI_POLICY.md) for more details. Do not abuse this policy.
The Cardinal project accepts contributions created with the assistance of generative AI tooling such as LLMs, with some caveats.
1. A human must be in the loop. Do not under any circumstances send us PRs that haven't been reviewed in full by a human. This is a bannable offense.
2. The buck stops at the first human in the loop. If your LLM tooling writes a bug, I will not treat it any differently from you writing the bug. If the bug is particularly harmful or malicious, you need to be ready to take responsibility for that.
3. Don't vibe-code your core business logic. We don't want to see low-quality AI slop in our geocoder or any of the other core features that define Cardinal maps as an offering in the maps space. If something has been done thousands of times by thousands of apps, we're less concerned about AI-generated boilerplate.
### Suggestions
Every time an agentic change is made:
1. Note which files are affected.
2. Force the agent to read all affected files and examine them for "self-consistency and code quality issues including duplicated logic, dead code and unused stubs".
Cardinal Maps is an open-soure mapping application focused on helping you get around while respecting your privacy.
We do not collect your location data directly, but we do collect data in certain circumstances that is related to user location, or can be used to infer user location with some nonzero probability.
## Offline Mode
First things first, if you use Cardinal Maps in offline mode, the only data we collect is which areas of the earth you choose to download maps for, with one exception. We don't have analytics, don't show or target ads, or any do of the other invasive things that most other apps do. If you use the app offline, your location data never leaves your device.
The exception to this rule is when you have the "fetch transit information even while offline" setting enabled. This setting is enabled by default, but can be diabled easily in the Offline Settings screen, which is accessible by tapping the Cardinal icon in the top left of the screen and tapping "Offline Settings".
## Online Mode
In order to provide an online mode, we do collect some information, but we've limited it to the information that we absolutely must have in order to provide the online service in question.
### Configurable backends
Cardinal Maps allows you to configure the application so that you can choose to send search and routing requests to whomever you choose. If you decide that you trust e.g. Stadia Maps more than you trust maps.earth (the default) you can configure the app to send your search and routing requests to them instead. You can also point the app at a self-hosted service if you decide you only trust yourself. Once you modify these advanced settings, the information described in the sections below will be sent to whoever it is that you choose, rather than to us.
#### Online search
We collect your search queries in online mode. We need this information in order to provide you search results. If you search for "Paris, France", we need that raw text in order to look up where Paris is in our database.
#### Online routing
We collect the "to" and "from" locations on your routing requests. If you choose to give the app location permissions, the "from" endpoint for your online routing requests will sometimes be your current location, and that location will be sent to our servers. If you do not choose to give the app location permissions, you can fetch routes for whichever locations you choose. We have no way of knowing whether the route requests we receive correspond to a user's location or not. This information is processed ephemerally and kept in our logs that are typically kept for about a week. We don't have any log persistence set up, but neither do we make any concerted effort to wipe our logs at fixed intervals. If you would like this feature, please help us out! Our default backend, maps.earth, is powered by Headway, an open-source web maps stack. We'd love an audit to make sure our logs aren't being retained for any longer than strictly necessary.
