ROS 2 On-boarding Guide¶
The purpose of this guide is supplement the on-boarding of new developers when they join the ROS 2 team. It is mostly used by the ROS 2 team, but it might be useful for others as well.
Request access to the GitHub organizations¶
Our code is federated across a few GitHub organizations, you’ll want access to them so you can make pull requests with branches rather than forks:
Request access to the buildfarm¶
The build farm is hosted at: ci.ros2.org
To request access send an email to firstname.lastname@example.org.
How to give access?¶
Your GitHub username must be added with the same permissions as existing users to Jenkins (http://ci.ros2.org/configureSecurity/). This can be done by any existing user.
Request access to the Google drive ROS2 folder¶
Only do this if you’re working at OSRF or need access to a particular document. To request access send an email to email@example.com (anybody on the mailing list can share it).
Choose a DDS domain ID¶
ROS2 uses DDS as the underlying transport and DDS supports a physical segmentation of the network based on the “domain ID” (it is used to calculate the multicast port.
We use a unique value for this on each machine to keep our ROS2 nodes from interfering from each other.
We expose this setting via the
ROS_DOMAIN_ID environment variable and use a document to ensure we don’t accidentally choose the same one as someone else.
This is, however, only important for people who will be working on the OSRF network, but it isn’t a bad idea to set up at any organization with multiple ROS 2 users on the same network.
Get a Personal ROS_DOMAIN_ID¶
To ensure it is always set, add this line to your
~/.bashrc or equivalent:
Watching ROS 2 Repositories¶
We try to spread our responsibilities out across the team and so we ask everyone to watch the main repositories for ROS 2.
What am I currently watching?
How do I watch a repository?
Which repositories should I watch?
All the repositories listed in the ros2.repos file, included the commented out ones,
Also all of these extra repositories from the ROS 2 organization:
We track all open tickets and current PRs using waffle.io: https://waffle.io/ros2/ros2
Higher level tasks are tracked on the internal (private) Jira: https://osrfoundation.atlassian.net/projects/ROS2
The usual workflow is (this list is a work in progress):
Discuss design (GitHub ticket, and a meeting if needed)
Assign implementation to a team member
Write implementation on a feature branch
Please check out the developer guide for guidelines and best practices
Enable and run linters
Run tests locally using
colcon test(see colcon tutorial)
Once everything builds locally without warnings and all tests are passing, run CI on your feature branch:
Go to ci.ros2.org
Log in (top right corner)
Click on the
Click “Build with Parameters” (left column)
In the first box “CI_BRANCH_TO_TEST” enter your feature branch name
If built without warnings, errors and test failures, post the links of your jobs on your PR or high level ticket aggregating all your PRs (see example here)
Note that the markdown for these badges is in the console output of the
To get the PR reviewed, you need to put the label “in review”:
Through github interface:
Click on “” next to labels
Remove “in progress” label if applicable
Add “in review” label
Drag your PR to the “in review” column
When the PR has been approved:
the person who submitted the PR merges it using “Squash and Merge” option so that we keep a clean history
If the commits deserve to keep separated: squash all the nitpick/linters/typo ones together and merge the remaining set
Note: each PR should target a specific feature so Squash and Merge should make sense 99% of the time
Delete the branch once merged
Here are some tips on how to use our Kanban board on waffle.io:
Assigning labels: drag and drop cards to the column with the label you want to assign
Connecting Issues/PR: Waffle allows to connect cards together using keywords
Note1: The keywords need to be placed in the 1st comment of the GitHub ticket
Note2: Waffle uses the “simplified” GitHub reference and not the full URL to connect card.
Does not work:
“connects to https://github.com/ros2/rosidl/issues/216”
In the same repo: “connects to #216”
In another repo: “connects to ros2/rosidl#216”
Build Farm Introduction¶
The build farm is located at ci.ros2.org.
Every night we run nightly jobs which build and run all the tests in various scenarios on various platforms. Additionally, we test all pull requests against these platforms before merging.
This is the current set of target platforms and architectures, though it evolves overtime:
Ubuntu 16.04 Xenial
macOS 10.12 Sierra
There several categories of jobs on the buildfarm:
manual jobs (triggered manually by developers):
ci_linux: build + test the code on Ubuntu Xenial
ci_linux-aarch64: build + test the code on Ubuntu Xenial on an ARM 64-bit machine (aarch64)
ci_osx: build + test the code on MacOS 10.12
ci_windows: build + test the code on Windows 10
ci_launcher: trigger all the jobs listed above
nightly (run every night):
Debug: build + test the code with CMAKE_BUILD_TYPE=Debug
Release: build + test the code with CMAKE_BUILD_TYPE=Release
Repeated: build then run each test up to 20 times or until failed (aka flakyness hunter)
nightly_linux_coverage: build + test the code + analyses coverage for c/c++ and python
results are exported as a cobertura report
packaging (run every night, against fastrtps; result is bundled into an archive):