Contributing to Meshtastic-Android

Thank you for your interest in contributing to Meshtastic-Android! We welcome contributions from everyone.

How to Contribute

Fork the repository and create your branch from main.
Keep each change focused — one concern per commit.
Test your changes thoroughly before submitting a pull request.
Submit a pull request (PR) with a clear description of your changes and the problem they solve.
If you are addressing an existing issue, please reference it in your PR (e.g., Fixes #123).
First-time contributors are asked to sign the CLA — the CLA-assistant bot will prompt you on your first PR.

Code Style

Follow the Kotlin Coding Conventions for Kotlin code.
Use Android Studio's default formatting settings.
We use spotless for automated code formatting. You can run ./gradlew spotlessApply to format your code automatically.
- You can also run ./gradlew spotlessInstallGitPrePushHook -Dorg.gradle.isolated-projects=false --no-configuration-cache to install a pre-push Git hook that will run a spotlessCheck.
Write clear, descriptive variable and function names.
Add comments where necessary, especially for complex logic.
Keep methods and classes focused and concise.
Strings: Use localised strings via the Compose Multiplatform Resource library in :core:resources.
- Do not use the legacy androidApp/src/main/res/values/strings.xml.
- Definition: Add strings to core/resources/src/commonMain/composeResources/values/strings.xml.
- Usage:
```
import org.jetbrains.compose.resources.stringResource
import org.meshtastic.core.resources.Res
import org.meshtastic.core.resources.your_string_key

Text(text = stringResource(Res.string.your_string_key))
```

Linting

Meshtastic-Android uses Detekt for static code analysis and linting of Kotlin code.

Run ./gradlew detekt before submitting your pull request to ensure your code passes all lint checks.
Fix any Detekt warnings or errors reported in your code.
Suppress individual warnings only as a last resort.
You can find Detekt configuration in the config/detekt directory. If you believe a rule should be changed or suppressed, discuss it in your PR.

Testing

Meshtastic-Android uses unit tests, Robolectric JVM tests, and instrumented UI tests to ensure code quality and reliability.

Unit tests are located in the src/test/ directory of each module.
Compose UI Tests (JVM) are preferred for component testing and are also located in src/test/ using Robolectric.
Instrumented tests (including full E2E UI tests) are located in src/androidTest/. For Compose UI, use the Jetpack Compose Testing APIs.

Guidelines for Testing

Add or update tests for any new features or bug fixes.
Ensure all tests pass by running:
- ./gradlew test for unit and Robolectric tests (pure-Android modules)
- ./gradlew allTests for KMP module tests (core:*, feature:*) — neither test nor allTests alone is sufficient; both must pass.
- ./gradlew kmpSmokeCompile when touching any KMP module — compiles the non-Android targets the unit tests don't cover
- ./gradlew connectedAndroidTest for instrumented tests
For UI components, write Robolectric Compose tests where possible for faster execution.
If your change is difficult to test, explain why in your pull request.

Pull Requests

Branches use conventional-commit style prefixes, e.g. feat/<topic>:
- feat/ — new user-visible behavior
- fix/ — bug fixes
- chore/ — tooling, deps, CI, cleanup
- docs/ — documentation only
- build/ — build system changes
- ci/ — CI workflow changes
- refactor/ — code structure changes
- test/ — test additions or fixes
- deps/ — dependency updates
Spec-driven work takes no prefix from that list: a numeric spec prefix (005-tak-v2-protocol) or the timestamp form YYYYMMDD-HHMMSS-feature-name created by /speckit.git.feature. Both are valid.
release/* and automation/* are reserved for maintainers and automated workflows.
Ensure your branch is up to date with the latest main branch before submitting a PR.
Provide a meaningful title and description for your PR.
Include information on how to test and/or replicate if it is not obvious.
Include logs where they show the behavior, as a fenced block rather than a screenshot of text. For UI changes see Screenshots below.
Be responsive to feedback and make requested changes promptly.
Squash commits if requested by a maintainer.

Writing the description

Delete the tips block from the template first, then:

Lead with why. One or two sentences on the problem the change solves, before any list of what changed. If it addresses an issue, say Fixes #123.
Group what changed under whichever of these apply, and omit the rest: 🌟 New Features · 🛠️ Refactoring & Architecture · 🐛 Bug Fixes · 🧹 Chores (dependencies, formatting, docs).
Call out architecture moves. Files moving androidMain → commonMain, or Views → Compose, are a KMP migration milestone — say so explicitly rather than leaving it to the diff.
Add a "Testing Performed" section whenever tests were added or changed, listing them. If a change is hard to test, say why there instead.

Screenshots

UI changes want images — anything touching Compose, layouts, theming, navigation, feature/** or core/ui/**. Use a Before / After table for a visual change or fix:

Before	After

Paste or drag images directly into the PR so GitHub hosts them, or reference a committed image by commit-SHA raw URL (https://raw.githubusercontent.com/<owner>/<repo>/<sha>/<path>, spaces encoded as %20) so the link survives the branch being deleted. Never use an external image service.

Never invent a URL or a placeholder image. If a UI change has no real screenshot yet, leave the template's commented image block in place for the author to fill in.

Issue Reporting

Search existing issues before opening a new one to avoid duplicates.
Provide a clear and descriptive title.
Include steps to reproduce, expected behavior, and actual behavior.
Attach logs, screenshots, or other helpful context if applicable.

Community Standards

Be respectful and considerate in all interactions.
The Meshtastic Android project is subject to the Meshtastic code of conduct.
Help others by reviewing pull requests and answering questions when possible.

Thank you for helping make Meshtastic-Android better!

6.8 KiB Raw Blame History