Contributing to Beemuu.

Easiest paths to contribute

If you have a BMW and 30 minutes, you can contribute. The four paths in increasing order of effort:

1. Report an issue.

   Found a bug or have a feature idea? Open a GitHub issue. No code required.

2. Add a community TOML file.

   Add a DTC text, a community opinion, or a freeze schema. Pure data; no Rust required. Schema documented in the repo.

3. File a real-car verification report.

   Use the docs/validation/ harness docs to confirm a parameter, a routine ID, or a DID on your car. PR the report; a maintainer reviews and flips the verification label.

4. Open a Rust PR.

   Add a new engine profile, decoder, or service-function routine ID. Tier B code (transport, protocol, commands.rs) requires human review; everything else is auto-merge eligible.

TOML data contributions

Most contributions to Beemuu are TOML files. The community data directory is structured as:

community/
├── opinions/         # Per-DTC repair paths contributed by owners + indie techs
├── profiles/         # Engine profiles with verified/pending parameters
├── freeze/           # Freeze-frame schemas per ECU
├── stories/          # Diagnostic-story knowledge (generic, N55-specific)
└── testplans/        # Guided test-plan walkthroughs (PR-style)

Each subdirectory has a README explaining the schema. The validation harness is automated — a TOML parse gate runs in CI; a broken data file fails the build rather than silently loading.

Adding a DTC

The DTC seed is in backend/seed_bmw.py and backend/seed_bmw_dim01.py. Adding a new code is a Python edit plus a TOML overlay if you want to extend the description or likely-causes. See CONTRIBUTING.md for the schema.

Adding a community opinion

Drop a TOML file at community/opinions/<code>.toml with the opinion’s text, severity, DIY / indie / dealer cost range, and a citation. The schema is in community/opinions/README.md.

Adding an engine profile

Drop a TOML at community/profiles/<engine>.toml with the parameter catalog. Each parameter has a query path (OBD-II PID or UDS DID) and a decoder. See community/profiles/README.md.

Verification reports

The strongest contribution is a real-car verification report. The project maintains a set of harness docs:

• docs/validation/dtc-history.md — verify DTC history behaviour.
• docs/validation/injector-validation.md — verify injector-time PIDs.
• docs/validation/service-functions.md — verify service-function routine IDs.
• docs/validation/u8_enum-validation.md — verify enum PIDs.
• docs/validation/can-broadcast.md — verify CAN broadcast decoder scaling.
• docs/validation/n62-real-car.md — N62-specific verification harness.
• docs/validation/testplans.md — verify guided test plans.
• docs/validation/freeze-frame.md — verify freeze-frame schema.

Each harness is a step-by-step checklist with pass/fail boxes. Run it on your car, PR the report, a maintainer reviews and flips the verification label in the matching TOML.

Rust contributions

Rust PRs are welcome for new engine profiles (in src-tauri/src/community.rs), new decoders (in src-tauri/src/data/live.rs), new DTCs (in backend/seed_bmw*.py), and bug fixes throughout. Tier B code paths (transport/**, protocol/**, commands.rs) require human review; everything else is auto-merge eligible.

Run the local test suite before opening a PR:

cargo test --manifest-path src-tauri/Cargo.toml
pytest backend/tests/ -q
node --test src/js/*.test.cjs

The CI workflow runs the same set on every PR. Open the PR against main; the roadmap lists what is ready to claim.

Documentation

Documentation is a Tier A surface and auto-merge eligible. The README, the CHANGELOG, the per-engine validation harnesses, the per-cycle plan docs, and the in-app help text are all open for fixes and additions.

For substantial changes, open an issue first to discuss the approach. Small fixes — typos, broken links, missing examples — can be PR’d directly.

PR process

1. Fork the repo and create a branch.

   Branch from main. Use a descriptive branch name (feat/community-opinion-P0171, fix/n62-temperature-display).

2. Make your change.

   Smallest change that satisfies the task. No drive-by refactors.

3. Run the local test suite.

   cargo test, pytest backend/tests/ -q, node --test. The CI workflow runs the same set; a PR that fails CI doesn’t get reviewed.

4. Open the PR against main.

   Title: short description of the change. Body: what changed, why, how it was verified. Link any related issue.

5. Wait for review.

   Tier A PRs are auto-merged once checks are green. Tier B PRs need human review.

6. Follow up.

   If review finds issues, address them in the same PR. New findings become new issues, never new scope on the same PR.

Contributing questions