ROS 2 developer guide¶
Table of Contents
This page defines the practices and policies we employ when developing ROS 2.
Some principles are common to all ROS 2 development:
Shared ownership: Everybody working on ROS 2 should feel ownership over all parts of the system. The original author of a chunk of code does not have any special permission or obligation to control or maintain that chunk of code. Everyone is free to propose changes anywhere, to handle any type of ticket, and to review any pull request.
Be willing to work on anything: As a corollary to shared ownership, everybody should be willing to take on any available task and contribute to any aspect of the system.
Ask for help: If you run into trouble on something, ask your fellow developers for help, via tickets, comments, or email, as appropriate.
Packages can ascribe to different levels of quality based on the development practices they adhere to, as per the guidelines in REP 2004: Package Quality Categories. The categories are differentiated by their policies on versioning, testing, documentation, and more.
The following sections are the specific development rules we follow to ensure core packages are of the highest quality (‘Level 1’). We recommend all ROS developers strive to adhere to the following policies to ensure quality across the ROS ecosystem.
We will use the Semantic Versioning guidelines (
semver) for versioning.
We will also adhere to some ROS-specific rules built on top of
semver's full meaning:
Major version increments (i.e. breaking changes) should not be made within a released ROS distribution.
Patch (interface-preserving) and minor (non-breaking) version increments do not break compatibility, so these sorts of changes are allowed within a release.
Major ROS releases are the best time to release breaking changes. If a core package needs multiple breaking changes, they should be merged into their integration branch (e.g. master) to allow catching problems in CI quickly, but released together to reduce the number of major releases for ROS users.
For compiled code, the ABI is considered part of the public interface. Any change that requires recompiling dependent code is considered major (breaking).
We enforce API stability for core packages in Dashing and Eloquent even though their major version components are
0, despite SemVer’s specification regarding initial development.
Subsequently, packages should strive to reach a mature state and increase to version
1.0.0so to match
These rules are best-effort. In unlikely, extreme cases, it may be necessary to break API within a major version/distribution. Whether an unplanned break increments the major or minor version will be assessed on a case-by-case basis.
Public API declaration¶
semver, every package must clearly declare a public API.
We will use the “Public API Declaration” section of the quality declaration of a package to declare what symbols are part of the public API.
For most C and C++ packages the declaration is any header that it installs. However, it is acceptable to define a set of symbols which are considered private. Avoiding private symbols in headers can help with ABI stability, but is not required.
For other languages like Python, a public API must be explicitly defined, so that it is clear what symbols can be relied on with respect to the versioning guidelines. The public API can also be extended to build artifacts like configuration variables, CMake config files, etc. as well as executables and command line options and output. Any elements of the public API should be clearly stated in the package’s documentation. If something you are using is not explicitly listed as part of the public API in the package’s documentation, then you cannot depend on it not changing between minor or patch versions.
Where possible, we will also use the tick-tock deprecation and migration strategy for major version increments. New deprecations will come in a new distribution release, accompanied by compiler warnings expressing that the functionality is being deprecated. In the next release, the functionality will be completely removed (no warnings). We will not add deprecations after a distribution is released.
Example of function
foo deprecated and replaced by function
[[deprecated(“use bar()”)]] void foo(); <br> void bar();
All changes must go through a pull request.
We will enforce the Developer Certificate of Origin (DCO) on pull requests in ROSCore repositories.
It requires all commit messages to contain the
Signed-off-byline with an email address that matches the commit author.
You can pass
git commitinvocation or write the expected message manually (e.g.
Signed-off-by: Your Name Developer <firstname.lastname@example.org>).
DCO is not required for pull requests that only address whitespace removal, typo correction, and other trivial changes.
Always run CI jobs for all tier 1 platforms for every pull request and include links to jobs in the pull request. (If you don’t have access to the Jenkins job someone will trigger the jobs for you.)
A minimum of 1 approval from a fellow developer who did not author the pull request is required to consider it approved. Approval is required before merging.
Packages may choose to increase this number.
Any required changes to documentation (API documentation, feature documentation, release notes, etc.) must be proposed before merging related changes.
Guidelines for backport PRs¶
When changing an older version of ROS:
Make sure the features or fixes are accepted and merged in the master branch before opening a PR to backport the changes to older versions.
When backporting to older versions, also backport to any [newer, still supported versions](https://index.ros.org/doc/ros2/Releases/), even non-LTS versions.
If you are backporting a single PR in its entirety, title the backport PR “[Distro] <name of original PR>”. If backporting a subset of changes from one or multiple PRs, the title should be “[Distro] <description of changes>”.
Link to all PRs whose changes you’re backporting from the description of your backport PR. In a Dashing backport of a Foxy change, you do not need to link to the Eloquent backport of the same change.
All packages should have these documentation elements present in their README or linked to from their README:
Description and purpose
Definition and description of the public API
How to build and install (should reference external tools/workflows)
How to build and run tests
How to build documentation
How to develop (useful for describing things like
python setup.py develop)
License and copyright statements
Each source file must have a license and copyright statement, checked with an automated linter.
Each package must have a LICENSE file, typically the Apache 2.0 license, unless the package has an existing permissive license (e.g. rviz uses three-clause BSD).
Each package should describe itself and its purpose assuming, as much as possible, that the reader has stumbled onto it without previous knowledge of ROS or other related projects.
Each package should define and describe its public API so that there is a reasonable expectation for users about what is covered by the semantic versioning policy. Even in C and C++, where the public API can be enforced by API and ABI checking, it is a good opportunity to describe the layout of the code and the function of each part of the code.
It should be easy to take any package and from that package’s documentation understand how to build, run, build and run tests, and build the documentation. Obviously we should avoid repeating ourselves for common workflows, like build a package in a workspace, but the basic workflows should be either described or referenced.
Finally, it should include any documentation for developers.
This might include workflows for testing the code using something like
python setup.py develop, or it might mean describing how to make use of extension points provided by you package.
This one gives an example of docs which describe the public API
This is an example of describing an extension point for a package
(API docs are not yet being automatically generated)
All packages should have some level of system, integration, and/or unit tests.
Unit tests should always be in the package which is being tested and should make use of tools like
Mock to try and test narrow parts of the code base in constructed scenarios.
Unit tests should not bring in test dependencies that are not testing tools, e.g. gtest, nosetest, pytest, mock, etc…
Integration tests can test interactions between parts of the code or between parts of the code and the system. They often test software interfaces in ways that we expect the user to use them. Like Unit tests, Integration tests should be in the package which is being tested and should not bring in non-tool test dependencies unless absolutely necessary, i.e. all non-tool dependencies should only be allowed under extreme scrutiny so they should be avoided if possible.
System tests are designed to test end-to-end situations between packages and should be in their own packages to avoid bloating or coupling packages and to avoid circular dependencies.
In general minimizing external or cross package test dependencies should be avoided to prevent circular dependencies and tightly coupled test packages.
All packages should have some unit tests and possibly integration tests, but the degree to which they should have them is based on the package’s quality category. The following subsections apply to ‘Level 1’ packages:
We will provide line coverage, and achieve line coverage above 95%. If a lower percentage target is justifiable, it must be prominently documented. We may provide branch coverage, or exclude code from coverage (test code, debug code, etc.). We require that coverage increase or stay the same before merging a change, but it may be acceptable to make a change that decreases code coverage with proper justification (e.g. deleting code that was previously covered can cause the percentage to drop).
We strongly recommend performance tests, but recognize they don’t make sense for some packages. If there are performance tests, we will choose to either check each change or before each release or both. We will also require justification for merging a change or making a release that lowers performance.
Some practices are common to all ROS 2 development.
These practices don’t affect package quality level as described in REP 2004, but are still highly recommended for the development process.
When filing an issue please make sure to:
Include enough information for another person to understand the issue. In ROS 2, the following points are needed for narrowing down the cause of an issue. Testing with as many alternatives in each category as feasible will be especially helpful.
The operating system and version. Reasoning: ROS 2 supports multiple platforms, and some bugs are specific to particular versions of operating systems/compilers.
The installation method. Reasoning: Some issues only manifest if ROS 2 has been installed from “fat archives” or from Debians. This can help us determine if the issue is with the packaging process.
The specific version of ROS 2. Reasoning: Some bugs may be present in a particular ROS 2 release and later fixed. It is important to know if your installation includes these fixes.
The DDS/RMW implementation being used (see this page for how to determine which one). Reasoning: Communication issues may be specific to the underlying ROS middleware being used.
The ROS 2 client library being used. Reasoning: This helps us narrow down the layer in the stack at which the issue might be.
Include a list of steps to reproduce the issue.
In case of a bug consider to provide a short, self contained, correct (compilable), example. Issues are much more likely to be resolved if others can reproduce them easily.
Mention troubleshooting steps that have been tried already, including:
A pull request should only focus on one change. Separate changes should go into separate pull requests. See GitHub’s guide to writing the perfect pull request.
A patch should be minimal in size and avoid any kind of unnecessary changes.
A pull request must contain minimum number of meaningful commits.
You can create new commits while the pull request is under review.
Before merging a pull request all changes should be squashed into a small number of semantic commits to keep the history clear.
But avoid squashing commits while a pull request is under review. Your reviewers might not notice that you made the change, thereby introducing potential for confusion. Plus, you’re going to squash before merging anyway; there’s no benefit to doing it early.
Any developer is welcome to review and approve a pull request (see General Principles).
When you start reviewing a pull request, comment on the pull request so that other developers know that you’re reviewing it.
Pull-request review is not read-only, with the reviewer making comments and then waiting for the author to address them. As a reviewer, feel free to make minor improvements (typos, style issues, etc.) in-place. As the opener of a pull-request, if you are working in a fork, checking the box to allow edits from upstream contributors will assist with the aforementioned. As a reviewer, also feel free to make more substantial improvements, but consider putting them in a separate branch (either mention the new branch in a comment, or open another pull request from the new branch to the original branch).
Any developer (the author, the reviewer, or somebody else) can merge any approved pull request.
We will version all libraries within a package together. This means that libraries inherit their version from the package. This keeps library and package versions from diverging and shares reasoning with the policy of releasing packages which share a repository together. If you need libraries to have different versions then consider splitting them into different packages.
The default branch (in most cases the master branch) must always build, pass all tests and compile without warnings. If at any time there is a regression it is the top priority to restore at least the previous state.
Always build with tests enabled.
Always run tests locally after changes and before proposing them in a pull request. Besides using automated tests, also run the modified code path manually to ensure that the patch works as intended.
Always run CI jobs for all platforms for every pull request and include links to the jobs in the pull request.
For more details on recommended software development workflow, see Software Development Lifecycle section.
When updating RMW API, it is required that RMW implementations for the Tier 1 middleware libraries are updated as well.
For example, a new function
rmw_foo() introduced to the RMW API must be implemented in the following packages (as of ROS Crystal):
Updates for non-Tier 1 middleware libraries should also be considered if feasible (e.g. depending on the size of the change). See REP-2000 for the list of middleware libraries and their tiers.
To help organize work on ROS 2, the core ROS 2 development team uses kanban-style GitHub project boards.
Not all issues and pull requests are tracked on the project boards, however. A board usually represents an upcoming release or specific project. Tickets can be browsed on a per-repo basis by browsing the ROS 2 repositories’ individual issue pages.
The names and purposes of columns in any given ROS 2 project board vary, but typically follow the same general structure:
To do: Issues that are relevant to the project, ready to be assigned
In progress: Active pull requests on which work is currently in progress
In review: Pull requests where work is complete and ready for review, and for those currently under active review
Done: Pull requests and related issues are merged/closed (for informational purposes)
To request permission to make changes, simply comment on the tickets you’re interested in. Depending on the complexity, it might be useful to describe how you plan to address it. We will update the status (if you don’t have the permission) and you can start working on a pull request. If you contribute regularly we will likely just grant you permission to manage the labels etc. yourself.
Defensive programming: ensure that assumptions are held as early as possible. E.g. check every return code and make sure to at least throw an exception until the case is handled more gracefully.
All error messages must be directed to
Declare variables in the narrowest scope possible.
Keep group of items (dependencies, imports, includes, etc.) ordered alphabetically.
Avoid using direct streaming (
stderrto prevent interleaving between multiple threads.
Avoid using references for
std::shared_ptrsince that subverts the reference counting. If the original instance goes out of scope and the reference is being used it accesses freed memory.
The filesystem layout of packages and repositories should follow the same conventions in order to provide a consistent experience for users browsing our source code.
src: contains all C and C++ code
Also contains C/C++ headers which are not installed
include: contains all C and C++ headers which are installed
<package name>: for all C and C++ installed headers they should be folder namespaced by the package name
<package_name>: contains all Python code
test: contains all automated tests and test data
doc: contains all the documentation
package.xml: as defined by REP-0140 (may be updated for prototyping)
CMakeLists.txt: only ROS packages which use CMake
setup.py: only ROS packages which use Python code only
README: can be rendered on Github as a landing page for the project
This can be as short or detailed as is convenient, but it should at least link to project documentation
Consider putting a CI or code coverage tag in this README
It can also be
.rstor anything else that Github supports
CONTRIBUTING: describes the contribution guidelines
This might include license implication, e.g. when using the Apache 2 License.
LICENSE: a copy of the license or licenses for this package
CHANGELOG.rst: REP-0132 compliant changelog
Each package should be in a subfolder which has the same name as the package. If a repository contains only a single package it can optionally be in the root of the repository.
Presently, we don’t use adhere to the practices in this section, but believe they would be beneficial to the development process and hope to employ them officially in the future.
This section describes step-by-step how to plan, design, and implement a new feature:
Creating the Design Document
Tasks requiring changes to critical parts of ROS 2 should have design reviews during early stages of the release cycle. If a design review is happening in the later stages, the changes will be part of a future release.
An issue should be created in the appropriate ros2 repository, clearly describing the task being worked on.
It should have a clear success criteria and highlight the concrete improvements expected from it.
If the feature is targeting a ROS release, ensure this is tracked in the ROS release ticket (example).
Writing the design document¶
Design docs must never include confidential information. Whether or not a design document is required for your change depends on how big the task is.
You are making a small change or fixing a bug:
A design document is not required, but an issue should be opened in the appropriate repository to track the work and avoid duplication of efforts.
You are implementing a new feature or would like to contribute to OSRF-owned infrastructure (like Jenkins CI):
You should fork the repository and submit a pull request detailing the design.
Mention the related ros2 issue (for example,
Design doc for task ros2/ros2#<issue id>) in the pull request or the commit message. Detailed instructions are on the ROS 2 Contribute page. Design comments will made directly on the pull request.
If the task is planned to be released with a specific version of ROS, this information should be included in the pull request.
Design document review¶
Once the design is ready for review, a pull request should be opened and appropriate reviewers should be assigned.
It is recommended to include project owner(s) -
maintainers of all impacted packages (as defined by
package.xml maintainer field, see REP-140) - as reviewers.
If the design doc is complex or reviewers have conflicting schedules, an optional design review meeting can be setup. In this case,
Before the meeting
Send a meeting invite at least one week in advance
Meeting duration of one hour is recommended
Meeting invite should list all decisions to be made during the review (decisions requiring package maintainer approval)
- Meeting required attendees: design pull request reviewers
Meeting optional attendees: all OSRF engineers, if applicable
During the meeting
The task owner drives the meeting, presents their ideas and manages discussions to ensure an agreement is reached on time
After the meeting
The task owner should send back meeting notes to all attendees
If minor issues have been raised about the design:
The task owner should update the design doc pull request based on the feedback
Additional review is not required
If major issues have been raised about the design:
It is acceptable to remove sections for which there is no clear agreement
The debatable parts of the design can be resubmitted as a separate task in the future
If removing the debatable parts is not an option, work directly with package owners to reach an agreement
Once consensus is reached:
Ensure the ros2/design pull request has been merged, if applicable
Update and close the github issue associated with this design task
Before starting, go through the Pull requests section for best practices.
For each repo to be modified:
Modify the code, go to the next step if finished or at regular interval to backup your work.
Self review your changes using
git add -i.
Create a new signed commit using
git commit -s.
A pull request should contain minimal semantically meaningful commits (for instance, a large number of 1-line commits is not acceptable). Create new fixup commits while iterating on feedback, or optionally, amend existing commits using
git commit --amendif you don’t want to create a new commit every time.
Each commit must have a properly written, meaningful, commit message. More instructions here.
Moving files must be done in a separate commit, otherwise git may fail to accurately track the file history.
Either the pull request description or the commit message must contain a reference to the related ros2 issue, so it gets automatically closed when the pull request is merged. See this doc for more details.
Push the new commits.
Once the change is ready for code review:
Open a pull request for each modified repository.
Package owners who reviewed the design document should be mentioned in the pull request.
Code review SLO: although reviewing pull requests is best-effort, it is helpful to have reviewers comment on pull requests within a week and code authors to reply back to comments within a week, so there is no loss of context.
Iterate on feedback as usual, amend and update the development branch as needed.
Once the PR is approved, package maintainers will merge the changes in.