Contributor guide

Contributor guide

Contributions are welcome in software, functional safety, SOTIF, cybersecurity, AI safety, verification, documentation and vehicle integration. This page is the short version of contributing to LionDriver, which is the rule book, and of the inherited openpilot contributing guide, which covers the development setup and code conventions.

Rendered from the safety-relevant file list and the workflow files by infographics.py at every wiki sync.

Setting up

LionDriver inherits openpilot's setup. Ubuntu 24.04 is the primary target; macOS works for most of it and Windows through WSL 2. tools/README.md has the full steps.

git clone https://github.com/jherrodthomas/LionDriver.git
cd LionDriver
tools/op.sh setup
source .venv/bin/activate
scons -u

The assurance checks need only Python:

python3 assurance/trace/tools/check_trace.py          # hazard log, goals and assumptions
python3 assurance/case-records/tools/validate.py              # Living Safety Case records
python3 assurance/case-records/tools/generate_dashboard.py    # regenerate the dashboard after a record change
python3 assurance/case-records/tools/test_case.py             # validator self-tests

Branches and pull requests

• Branch from liondriver-dev and open the pull request against liondriver-dev. master tracks upstream openpilot and does not take LionDriver changes.
• Questions and bugs go to the issues. A review of a safety analysis is as valuable as code: comment on the work product in a pull request, or open an issue naming the work product and section.
• The PR review workflow labels each pull request by the paths it touches. The other workflows that run on it are listed in how the repository is organized.

Is my change safety-relevant?

A change is safety-relevant if it touches a path on the safety-relevant file list or changes an assurance work product. The list has three classes:

Class	What it covers	Examples
SR-A	Code or data in the ASIL path: the safety envelope on the panda microcontroller	opendbc_repo/opendbc/safety/, panda/board/
SR-Q	QM, SOTIF or cybersecurity elements that feed hazards, configure the envelope or affect freedom from interference	The Toyota car port, the car abstraction, controls, driver monitoring
SR-T	Build, test, CI, toolchain or dependency configuration that changes evidence or binaries	Workflows, coverage tooling, pinned toolchains

Anything not matched is not safety-relevant and takes the standard route. The list is owned by WP-P-01 configuration management and changes only through a change request.

What a safety-relevant pull request must include

1. Rationale. What the change does and why.
2. Impact analysis. Which hazards, safety goals, requirements, assumptions and evidence items it affects, following WP-M-12 and WP-P-02 change management. "No assurance object affected" is a valid result, with a reason.
3. Verification. The tests or analyses that show the change is correct, and their results.
4. Record updates. The affected records in assurance/case-records/ or assurance/trace/, with the dashboard regenerated.

What can and cannot change a review state

• Only a review record in assurance/case-records/reviews/, written by the named reviewer at the independence level the confirmation measures plan requires, can mark a claim or evidence item as accepted.
• A passing CI run, a passing test or an existing file does not accept anything. It can be evidence that a reviewer accepts.
• An AI-generated review is not a substitute for the required independent confirmation.
• Never edit status.json, the generated SVGs or the README dashboard block by hand. Change the records and regenerate.

Inherited code

Keep changes to inherited openpilot, opendbc and panda code minimal and local, so upstream updates stay mergeable. Upstream licences, copyright notices and attribution stay in place. Submodule pins change through the upstream management process, with an impact analysis.

Working with Claude sessions

Much of the drafting is done in Claude Code sessions under the project lead's direction. The rules those sessions follow are in CLAUDE.md and assurance/AGENTS.md: sort questions before asking, keep every question self-contained, ask in batches of ten, and record decisions in the register. A session's pull request is reviewed like any other. The session log lists what has been merged.

Where to get help

• Issues for anything about the project.
• Discussions for open-ended questions.
• Security problems go through SECURITY.md, never a public issue. See reporting a safety concern.