Contributing

The Clearpath Community Demos repository is community-driven — we welcome new demos, improvements, bug fixes, and documentation updates from anyone using a Clearpath platform.

How to contribute a new demo

  1. Fork the repository.
  2. Add your demo source code under demos/<your_demo_name>/ as a self-contained ROS 2 package (or set of packages).
  3. Include an example robot.yaml — provide a working Clearpath robot configuration that the demo was tested against under demos/<your_demo_name>/config/robot.yaml. This is the clearpath_config file describing the platform, sensors, and any payloads the demo expects. Reviewers and other users need this to reproduce your setup. Document any parts that must be edited (serial numbers, IPs, namespaces) in a comment at the top of the file.
  4. Add a documentation page under demos_docs/<your_demo_name>.md following the pattern of the existing demos. Include:
    • A short description.
    • Supported platform(s).
    • Prerequisites.
    • How to launch and what to expect.
    • A link to the example robot.yaml and any required edits.
  5. Open a pull request against main.

Code style

This repository uses pre-commit to run style and lint checks both locally and in CI. Install the hooks before committing:

python3 -m venv venv
. venv/bin/activate
pip install pre-commit
pre-commit install            # in the top-level dir of the repo

The configured hooks include:

  • Python — ruff for linting and formatting (config in .ruff.toml).
  • C / C++ — clang-format (config in .clang-format). Demos using C++ should use ament_cmake and enable ament_lint_auto in their CMakeLists.txt, mirroring the hello_clearpath example.
  • Spell checking — cspell; add new project-specific words to .cspell.json when needed.
  • GitHub Actions — actionlint validates the workflow files.
  • Generic — trailing whitespace, end-of-file newlines, merge-conflict markers, leaked credentials, and similar checks.

Other guidelines:

  • Follow the ROS 2 Developer Guide conventions.
  • Python demos use ament_python; C++ demos use ament_cmake. Keep packages self-contained — avoid cross-dependencies between demos.
  • Pin or document the ROS 2 distribution(s) and Clearpath software version(s) you tested against.

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0 that covers this repository.

Disclaimer

Demos in this repository are provided as-is by the community. They are not officially supported by Clearpath Robotics, by Rockwell Automation. Always review code before running it on hardware, and be mindful of safety when operating real robots.