CONTRIBUTING

Contributing to clearpath_config

Thanks for your interest in improving clearpath_config! This package is the entry point of the Clearpath ROS 2 system: it parses and validates a robot’s robot.yaml into a typed Python object tree that the Clearpath generators consume. Because of that central role, changes here can ripple through the rest of the stack, so please read the notes below before opening a pull request.

Getting started

Fork the repository and clone your fork.
Create a feature branch off jazzy:
```
git checkout -b my-feature jazzy
```

Install the pre-commit hooks (one-time setup):

pip install pre-commit
pre-commit install

Where things live

The top-level ClearpathConfig class delegates each top-level YAML key to a dedicated sub-config module (system, platform, links, manipulators, mounts, sensors). Shared plumbing (base classes, YAML read/write, type helpers) lives under clearpath_config/common/. See the Architecture section of the README for the full map.

A few conventions to keep in mind:

Use read_yaml/write_yaml from common/utils/yaml.py rather than calling PyYAML directly, so ordering and formatting stay consistent with the generators.
Each sub-config validates its own section and exposes typed accessors; keep new validation close to the section it belongs to.

Coding style

Follow PEP 8; the CI enforces flake8 with a 100-character line limit.
Docstrings and comments should follow pep257.
Keep changes focused. Avoid unrelated refactors in the same pull request.

Linting and formatting

This repository uses pre-commit to run linting and formatting checks (trailing whitespace, flake8, markdownlint, YAML checks, and more) before each commit. Run them against the whole tree before pushing:

pre-commit run --all-files

Tests

Unit tests are written with PyTest following the Good Integration Practices. Every file to be tested has a corresponding file with the same name and the suffix _test.py.

Run the suite from the package root:

cd .../clearpath_config
python3 -m pytest

Please add or update tests for any behavior you change, and make sure the full suite passes before opening a pull request.

Sample configurations

The clearpath_config/sample/ folder holds example configurations. Sample files whose names contain test (e.g. test_a300.yaml) are the fixtures consumed by clearpath_generator_tests, so adding or renaming one changes what CI validates.

Generator tests

Changes to clearpath_config (config structure, defaults, or test samples) may affect the output of the Clearpath generators. The clearpath_generator_tests repository versions the expected generator output and validates it through CI.

Before merging, ensure a corresponding branch with the same name exists in clearpath_generator_tests with regenerated samples. See the Development Workflow section of that repository for the full process.

Continuous integration

Two workflows run on every pull request:

clearpath_config_ci — a ROS build/test (build_and_test against the released testing/main repos, plus a source_build of clearpath_config).
Clearpath Config Python Package — flake8 linting and pytest.

clearpath_config sits at the root of the stack, so its own CI does not pull in upstream source branches — every job here depends only on this repository and should pass on its own. Upstream changes matter downstream: a change to config structure, defaults, or samples can alter the output of the Clearpath generators. That is validated by the clearpath_generator_tests CI, which pulls the matching-named branch from this repository. Expect those downstream generator tests to fail until a branch with the same name and regenerated samples exists in clearpath_generator_tests (see Generator tests above).

Submitting a pull request

Make sure pre-commit run --all-files and python3 -m pytest both pass.
Push your branch and open a pull request against jazzy.
Write a clear description of what the change does and why. Link any related issues.
If your change touches config structure, defaults, or samples, note the matching clearpath_generator_tests branch in the pull request description.

The changelog (CHANGELOG.rst) is maintained by the maintainers at release time, so you do not need to edit it in your pull request.

Reporting issues

Please open issues on the GitHub issue tracker and fill out the bug report template, which walks you through the details we need to reproduce the problem.

License

By contributing, you agree that your contributions will be licensed under the BSD-3-Clause license that covers this project.