Developer Setup Guide

[rr-tom-noble]

I feel that the Moveit Pull Requests documentation is missing a section on how to easily set up an environment to build and test changes, and set up integration with a forked repository.

For me, the most convenient method has been:

1. Create a fork of moveit2
2. Download the moveit/moveit2:-source Docker Image
3. Start an interactive container with git ssh keys mounted (I usually use the VSCode extension)
4. Source /opt/ros//setup.bash
5. Navigate to /ws_moveit/src/moveit2
6. Set the origin to your fork, checkout / create a new branch
7. Make changes to code
8. Run colcon build --cmake-args -DBUILD_TESTING=ON --packages-up-to
9. Run colcon test --packages-select
10. Check test failures with colcon test-result (I usually grep the output for specific tests -- there might be nicer ways of doing this)
11. Follow the existing guide to format / lint the code
12. Push changes
13. Raise PR from fork

I suppose this process really depends on developer preference, but I definitely found it daunting figuring out how to easily set up an environment when making my first PRs, so I feel like a guide for newcomers might be useful.

I may have also just missed an existing doc page, so this might be redundant. As far as I can see, it mainly relates to code style, running CI jobs locally, and just a reference to the source container as a thing that exists.

I also have a few questions:

• Do others feel like such a guide would be useful?
• Are there steps in my process that could be simplified, so that a guide would be as streamlined as possible?
• Are there nicer ways of running & filtering individual tests & results (partially for my own benefit too 😄 )

[TSNoble]

Regarding 10. I've now found that a good way of performing more granular test inspection is to run the test executable directly with gtest filters, as it's more featureful than the options colcon provides and presents the results out-of-the-box (though this only seems to work with tests that don't rely on ROS capabilities).

Alternatively colcon test --ctest-args ... provides some of the same features but, as far as I can tell, with less granular filtering options.

[TSNoble]

It might make more sense to split this into several how-to guides

• How to connect a Moveit Image to your local fork
• How to run tests locally, assert(false) not failing in tests but it should #3102 means there are some slightly unintuitive build args that need to be passed in for reliable test behaviour
• How to run more granular tests (repeat runs, shuffled runs, break on failure, filtering, etc...)