Contributing¶

The canonical contributor guide lives at the repository root in CONTRIBUTING.md. It is reproduced below so it is searchable alongside the CI/CD guide.

Contributing to 6.5_GUI¶

Welcome! This repo is a multi-component robotics monorepo (desktop GUI, STM32 firmware, C++ motion planner, and supporting tools). This guide covers the day-to-day workflow. For a deep dive on how CI/CD works and how it is set up, read the CI/CD guide.

1. Repository layout¶

Path	What it is	Build system
`gui/`	PySide6 desktop GUI (`owlgui_v2`)	`pyproject.toml`
`6.5/`	STM32 firmware + bench GUI + Flask `web_app` + CLI	PlatformIO
`planners/`	C++17 motion planner (OMPL/Pinocchio/Coal) + bridge	CMake
`6.8/`,`docs/`	Documentation	-

2. One-time setup¶

# Clone and enter the repo
git clone git@github.com:orangewood-co/6.5_GUI.git
cd 6.5_GUI

# Install and enable pre-commit (runs lint/format on every commit)
pip install pre-commit
pre-commit install

Then install only the component(s) you work on:

# GUI
pip install -e "gui/.[viz]" pytest

# Firmware
pip install platformio

# Planner (uses Docker so you don't hand-install OMPL/Pinocchio/Coal)
docker build -t owl-planners-ci -f planners/Dockerfile.ci planners

3. Branching¶

main is protected: no direct pushes. Everything lands via pull request.
Branch off main using a descriptive prefix:
feat/<short-desc> — new feature
fix/<short-desc> — bug fix
chore/<short-desc> — tooling, refactor, docs
dev/<topic> — longer-running integration work

git checkout main && git pull
git checkout -b feat/planner-cartesian-path

4. Commit messages¶

Follow the existing Conventional-Commits style already used in history:

feat: add cartesian path planning to the program page
fix(6.5): re-init CAN on rescan so motors recover without a reset
chore: bump ruff and clang-format hook versions

Format: type(optional-scope): summary, where type is one of feat, fix, chore, docs, refactor, test.

5. Before you push — run the checks locally¶

Running these locally catches problems before CI does:

# All formatting/lint hooks (fast)
pre-commit run --all-files

# GUI tests (Qt runs headless)
QT_QPA_PLATFORM=offscreen pytest gui/tests -v

# Firmware build (no board needed)
cd 6.5 && pio run -e nucleo_f446re

# Planner build + sanity test (inside the Docker image)
docker run --rm -v "$PWD/planners:/work" -w /work owl-planners-ci \
  bash -lc 'cmake -S . -B build && cmake --build build -j && ./build/collision_check_test'

6. Open a pull request¶

Push your branch: git push -u origin <branch>.
Open a PR against main. The template will prompt you for details.
CI runs automatically. Only the pipelines for paths you changed will run.
A code owner reviews. Address feedback with new commits.
Once all required checks are green and you have an approval, merge.

7. Hardware testing¶

CI can only build firmware and planner code — GitHub's runners have no robot attached. If your change affects motor behavior, test it on real hardware and note the setup in the PR. See the "Hardware-in-the-loop" section of the CI/CD guide for the longer-term plan.