Pre-commit

Install pre-commit and set up the git hooks:

pip install pre-commit
 
# from within repo root
pre-commit install

Formatting and Linting

All checks are defined in .pre-commit-config.yaml and run both locally via pre-commit and in CI via pre-commit/action, so the two are always in sync.

C++

Formatting rules are defined in .clang-format at the repo root. The C/C++ VSCode extension picks this up automatically — no extra configuration needed.

A custom hook also forbids __struct.hpp detail includes (e.g. foo/msg/detail/bar__struct.hpp). These are internal rosidl-generated headers that omit the is_message<> trait specialisation that rclcpp requires. Always use the full message header (e.g. foo/msg/bar.hpp) instead.

Python

Python files are formatted and linted with ruff. Default rules apply (no ruff.toml).

CI

Three GitHub Actions workflows run on every push and pull request:

Build — builds the package with colcon inside a ROS Humble container.
Docs — builds only the Doxygen target (no C++ compilation) and uploads the result as a downloadable artifact.
Pre-commit — runs pre-commit run --all-files. Fails on any violation.

API Documentation

Doxygen docs are not built by default. To generate them locally, pass -DBUILD_DOC=ON:

colcon build --packages-select controls --cmake-args -DBUILD_DOC=ON --cmake-target doxygen

Requires Doxygen (sudo apt install doxygen). Output is written to build/controls/docs/html/index.html.