Previous slide Next slide Toggle fullscreen Toggle overview view Open presenter view
ROS 2 Development Workflow
ROS 2 Development Workflow
This explains how to contribute to the ROS 2 project, from git basics to build, test, CI, and review.
Reference:
ROS 2 Development Workflow
Agenda
General git workflow
ROS 2 branches
Repository checkout & full source build
colcon build and tests
Jenkins ROS 2 CI
Issue / PR templates, QA & support
AI-assisted contribution policy
Contributing to ROS 2 documentation
ROS 2 Development Workflow
Two Contribution Tracks
Both share the same git / PR / DCO / review workflow.
ROS 2 Development Workflow
General git Workflow — Fork & Clone
ROS 2 uses the fork-and-pull-request model on GitHub. Fork the target repository into your namespace, then clone. Keep upstream as the source of truth; origin is your fork.
git clone git@github.com:<you>/rclcpp.git
cd rclcpp
git remote add upstream git@github.com:ros2/rclcpp.git
git fetch upstream
ROS 2 Development Workflow
General git Workflow — Branch & Commit
Create a topic branch off the correct base branch (usually rolling).
git checkout -b fix/executor-deadlock upstream/rolling
Write focused commits, one logical change per commit. Sign off every commit — the Developer Certificate of Origin (DCO) is mandatory.
git commit -s -m "Fix deadlock in MultiThreadedExecutor"
ROS 2 Development Workflow
General git Workflow — Pull Request Flow
Push the topic branch to your fork.
Open a PR against ros2/<repo> rolling.
Fill the PR template; link related issues.
Green CI + DCO + at least one maintainer approval .
Squash / rebase as requested, then a maintainer merges.
you:fix/... ──PR── ros2/repo:rolling ──(review + CI)── merge
ROS 2 Development Workflow
ROS 2 Branches — rolling is the trunk
rolling is the continuously developed development distribution. All new features and fixes land on rolling first . Named distribution branches are cut from rolling at release.
Branch
Purpose
rolling
active development, target of most PRs
lyrical / kilted / jazzy / humble
released distributions (maintenance)
ROS 2 Development Workflow
ROS 2 Branches — Backporting via Mergify
Fixes needed on released distros are backported from rolling.
Label the PR (e.g. backport-jazzy) so Mergify automates a cherry-pick PR.
Backports must respect REP 2000 API/ABI stability rules for released distros.
git cherry-pick -x <sha>
ROS 2 Development Workflow
ROS 2 is many repositories orchestrated by a .repos file.
Use vcstool to import the whole source tree.
mkdir -p ~/ros2_ws/src && cd ~/ros2_ws
wget https://raw.githubusercontent.com/ros2/ros2/rolling/ros2.repos
vcs import src < ros2.repos
vcs pull src
ROS 2 Development Workflow
Full Source Build — Dependencies
Resolve system dependencies with rosdep .
sudo rosdep init && rosdep update
rosdep install --from-paths src --ignore-src -y \
--rosdistro rolling
ROS 2 Development Workflow
colcon Build
colcon is the meta-build tool for ROS 2 workspaces.
colcon build --symlink-install \
--cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo
Useful options:
--packages-select / --packages-up-to — build a subset.
--symlink-install — edit Python/resources without rebuilding.
--event-handlers console_direct+ — stream build output.
ROS 2 Development Workflow
colcon Test
colcon test --packages-select rclcpp
colcon test-result --all --verbose
Test frameworks in ROS 2:
C++ : gtest / gmock
Python : pytest
Launch/integration : launch_testing
Every behavioral change should ship with a regression test .
ROS 2 Development Workflow
Code Style & Linters
ROS 2 enforces style automatically via ament_lint .
C++: ament_uncrustify, ament_cpplint, ament_cppcheck
Python: ament_flake8, ament_pep257
ament_copyright, ament_xmllint
Follow the ROS 2 Code Style (based on Google C++ Style with ROS additions).
ament_uncrustify --reformat src/rclcpp
ROS 2 Development Workflow
ROS 2 CI runs on a Jenkins build farm across platforms.
Coverage: Linux, Linux-aarch64, Windows, RHEL .
Nightly jobs build & test all of rolling from source.
Per-PR jobs validate a change against the full stack before merge.
ROS 2 Development Workflow
Jenkins CI — Running a PR Job
Maintainers trigger a CI run scoped to your PR packages.
Test with --packages-above-and-dependencies rclcpp
Job: ci_launcher → Linux / Linux-aarch64 / Windows / RHEL
The green/red result is posted back; all targets must pass .
You can reproduce a target locally with the same colcon invocation.
ROS 2 Development Workflow
Issue Templates
Repos ship issue templates under .github/ISSUE_TEMPLATE/.
Provide a minimal reproducible example :
ROS 2 distro & OS, RMW implementation
Install method (binary / source)
Exact steps, expected vs. actual behavior
Search existing issues first; discuss the approach before a large PR.
ROS 2 Development Workflow
PR Template & Review
Fill the PR template: what changed, why, how tested .
Checklist typically covers: tests added, docs updated, DCO signed.
Review expectations:
Respond to reviewer comments directly and technically.
Keep the PR focused; avoid unrelated churn.
Rebase, don't merge rolling into your branch repeatedly.
ROS 2 Development Workflow
AI Policy — The Rules
Author Ownership : you own and can defend every line; you sign the DCO. Don't use maintainers as an LLM validation service.
Zero-tolerance for hallucinations : PRs with non-existent APIs / config keys are closed immediately.
Disclosure : state clearly if an LLM generated structural code, tests, or docs.
No LLM-dump : write a concise, human-authored PR description and review replies.
ROS 2 Development Workflow
AI Policy — Responsible Workflow
Confirm the issue is valid; discuss the approach on the thread first.
Run the code locally — it compiles, lints, and passes tests .
Read your own diff line-by-line; remove verbose AI comments and cruft.
Explain the change in plain technical language yourself.
"Maintainers want to talk to you, the author — not to your chatbot."
ROS 2 Development Workflow
Contributing to ROS 2 Documentation
Source lives in ros2/ros2_documentation .
Built with Sphinx ; pages in reStructuredText or Markdown .
Branch per distribution: rolling, jazzy, humble …
Same fork → branch → DCO-signed commit → PR flow as code.
ROS 2 Development Workflow
Docs — Build & Preview Locally
git clone https://github.com/ros2/ros2_documentation.git
cd ros2_documentation
pip install -r requirements.txt
make html
Preview locally before opening the PR.
CI builds the site and runs link / style checks on your branch.
ROS 2 Development Workflow
Docs — Dev Container
ros2/ros2_documentation ships a Dev Container for a reproducible, zero-setup toolchain.
Open in VS Code → "Reopen in Container" (or GitHub Codespaces); it provisions Python, Sphinx, and all requirements.txt deps automatically.
Same make html build inside the container — no host pollution, identical to CI.
{
"image" : "mcr.microsoft.com/devcontainers/python:3" ,
"postCreateCommand" : "pip install -r requirements.txt"
}
ROS 2 Development Workflow
Docs — Test
Before opening the PR, run the same checks CI runs — locally or inside the Dev Container.
make test
make lint
make spellcheck
make linkcheck
make test-tools
Add legitimately-flagged words to codespell_whitelist.txt , and custom corrections to codespell_dictionary.txt — then make check-dictionaries / make sort-dictionaries.
Sphinx builds with -W, so warnings are errors ; a clean local run ≈ a green CI run.
ROS 2 Development Workflow
Summary — Getting Started Checklist
[ ] Fork, clone, add upstream
[ ] vcs import the source, rosdep install deps
[ ] colcon build + colcon test green locally
[ ] Topic branch, focused DCO-signed commits
[ ] Fill issue/PR templates; disclose AI use
[ ] Pass Jenkins CI on all platforms
[ ] Engage reviewers as the author
ROS 2 Development Workflow
References
This session focuses on the practical development workflow, not on ROS 2 concepts.
The goal is that after this, an attendee can build ROS 2 from source, make a change,
run tests / CI, and open a well-formed PR that respects project policy.
We cover both contribution tracks: core libraries (C++/Python) and documentation.
Emphasize: the collaboration mechanics are identical; only the toolchain differs.
Never push directly to ros2/*; always work through your own fork.
`-s` adds the "Signed-off-by:" trailer. PRs without DCO fail the DCO check.
Rebase onto latest rolling before requesting review to avoid stale conflicts.
Develop against rolling unless the fix is specific to an older released distro.
Released distributions are API/ABI stable; only bug fixes, no breaking changes.
ros2.repos pins each repo/branch. This is how the build farm assembles a workspace.
rosdep maps package.xml keys to apt/pip packages per platform.
Source install/setup.bash after build to overlay the workspace.
`colcon test` runs both unit tests and linters; test-result summarizes failures.
Run linters locally; CI will reject style violations otherwise.
ci.ros2.org is the developer CI (source build). build.ros.org is the release farm
that produces binary debs for distributions.
Contributors usually ask a maintainer to "run CI" and paste the job links in the PR.
A reproducible report is far more actionable than "it doesn't work".
Maintainer time is scarce; a tight, well-described PR gets reviewed faster.
The policy is a framework, not a permanent ban — but it sets clear boundaries.
Repeat offenses can lead to being blocked from the org repositories.
This mirrors good engineering practice regardless of whether AI was used.
Docs use the identical collaboration workflow; only the build tooling differs.
Always verify rendering and links locally to save review round-trips.
The Dev Container removes "works on my machine" issues — the environment matches CI,
so contributors (including newcomers) can build and preview docs without local setup.
These targets come straight from the ros2_documentation Makefile. `make test` is doc8
(style/whitespace, e.g. no trailing whitespace), not an umbrella target — run each check.
Catching spelling, dead links, and style issues locally saves maintainer review time.
If every box is checked, the PR is in great shape for review.
Thank you — questions welcome.