mg4/CONTRIBUTING.md

Contributing

This app runs on a car. That single fact drives everything below.

Ground rules

1. Telemetry never writes to the vehicle. The opt-in SWI69 WinClose integration is the only write exception: four-window closing, gated on P and readable 0 km/h, with a bounded pulse and STOP on completion, interruption or failure.
2. A property that cannot be read is omitted, never defaulted. Sending 0 for an unreadable battery level tells ABRP the car is empty and corrupts the user's route plan. Nullable in, absent from the payload.
3. Fail closed on anything security-shaped. Unknown update origin, mismatched signature, unreadable state: refuse, do not guess.
4. Say what you did not verify. Most of this code can only be fully tested on a vehicle. "Builds and unit tests pass, not tried on the car" is a perfectly good PR note. Silence implying it was road-tested is not.

Before opening a PR

mise run check      # permission gate + lint + unit tests

or, without mise:

bash .github/security/check-permissions.sh
./gradlew testStableDebugUnitTest testUnstableDebugUnitTest lintStableDebug

New behaviour needs a unit test. The pure-logic classes — TelemetryPayload, UploadCadence, UploadLog, OtaUpdater — are deliberately free of Android types so they can be tested on the JVM; put testable logic there rather than in the service.

Permissions

Any new uses-permission fails CI until it is added to .github/security/permission-allowlist.txt with a justification comment. This is deliberate: an app on someone's car should not gain capabilities quietly.

Channels

• stable — tagged releases, no self-update, no updater code in the APK.
• unstable — automated pre-releases that update themselves.

If you touch the updater, remember it installs code on a vehicle: the origin allowlist and the signature check are the whole defence.

Ways to help

Not every useful contribution is code:

• Bug reports — firmware generation, app version, what you did, what happened.
• Feature requests — describe the problem before the solution.
• Documentation — README, this guide, translations.
• Pull requests — see below.
• Testing pre-releases — install an unstable build and report what broke.
• Sponsorship — see below.

Contributing efficiently

Maintainer time and AI quota are the scarce resources here, ideas are not. If you have access to Claude Opus or another capable coding model, a finished pull request is worth much more than a feature request: someone still has to design, write, test and verify the request, and that someone has a limited quota too.

A pull request that lands quickly usually carries:

• The problem, in one or two sentences.
• The proposed solution, and what you rejected.
• The implementation, scoped to one concern.
• Tests — mise run check passes.
• Documentation updated: README, CHANGELOG, this guide where relevant.

Generate the change locally with whatever model you have, then read every line yourself before opening the PR. You are the author, not the model. Unreviewed generated code on a path that reaches the vehicle will be sent back.

Sponsorship

Maintaining EVSuite costs development time, test hardware and AI usage. If it is useful in your daily driving, consider sponsoring through GitHub Sponsors. Sponsorship covers those costs and gets fixes and features out faster.

Commit messages

Explain why, not what — the diff already says what. If you fixed something subtle, say what the failure looked like, so the next person recognises it.

Licensing

Read LICENSE.md first. Contributions are accepted under the MIT Licence, except changes to EVHardware/, which fall under its PolyForm Noncommercial licence.