Repository Guidelines

Project Structure & Module Organization

Work inside Cruise/, the ROS 2 workspace. Packages live under Cruise/src (uv_ai, uv_hm, uv_vision, uv_control_py, uv_launch_pkg, utils, models). Tests sit beside each package in test/; runtime helpers stay in scripts/run/, diagnostics in scripts/test/, captures in datas/. Keep models/ to pointers or download scripts and store large weights elsewhere. Purge build/, install/, and log/ artifacts-they are colcon outputs.

Build, Test, and Development Commands

Prime dependencies with rosdep install --from-paths src --ignore-src -r -y. Build everything via colcon build --symlink-install, then source the overlay (call install\setup.bat on Windows or source install/setup.bash). Use colcon build --packages-select <pkg> for tight loops, ros2 launch uv_launch_pkg launch.py for integrated bring-up, and colcon test --event-handlers console_cohesion+ (optionally with --packages-select) for automated checks.

Coding Style & Naming Conventions

Use 4-space indentation, lowercase module names, CapWords classes, and executables prefixed with their package (e.g., uv_vision -> uv_vision_node). Keep tunables in YAML or helper modules rather than hard-coding. Add type hints and concise docstrings for every ROS topic, service, or parameter. Run ament_flake8 and ament_pep257 until clean before committing.

Testing Guidelines

Write pytest-style files named test_<feature>.py inside each package's test/ folder. Mock hardware whenever possible; otherwise reuse captures from datas/ or diagnostics from scripts/test/. Execute colcon test --packages-select <pkg> to reproduce issues and attach log/latest_test/ snippets to bug reports. Keep tests deterministic so the console_cohesion handler stays readable.

Commit & Pull Request Guidelines

Adopt Conventional Commits (feat(vision): add depth fusion node) with <=72-character subjects and explanatory bodies referencing tickets in the footer. Pull requests must summarize the change, list verification commands (colcon build, focused colcon test, relevant ros2 launch), and link evidence for perception updates. Never commit build/, install/, log/, or large binaries; store weight references only.

Environment & Configuration Tips

Run scripts/run/permissions.sh (or the Windows analogue) before connecting new serial hardware. Surface every new parameter both in launch files and mirrored YAML configs so operators can tune without rebuilding. Record external model sources and hashes in PR descriptions, and keep credentials or proprietary captures outside the repo.