[Documentation] [TitleIndex] [WordIndex

ROS developer's guide

ROS is a large system, with lots of people writing lots of code. To keep things manageable, we have established the following development guidelines. Please follow these guidelines as you code.

See also:

Source control

We support using Git, Mercurial, Subversion and Bazaar for source control. As the ROS community is distributed, you are welcome to host your code anywhere that is publicly accessible (GitHub, Bitbucket, Google Code). The main ROS code base is hosted in several organization units on github.com. For the recommended repository usage please see RecommendedRepositoryUsage

Bug tracking

We use separate bug trackers for each package which include bug reports, enhancement requests, and task assignments. Usually you will find the link to the package-specific bug tracker on the Wiki page of the package.

For packages hosted on GitHub this is commonly the issue tracker of the repository.

The maintainer will assign a milestone to each reported issue. This should give the reporter a reasonable feedback when this issue will be addressed. These milestone are usually ROS releases (like Groovy or Hydro) or more fine grain milestones (like Hydro beta 1). Furthermore the milestone untargeted is used when a issue will likely not get fixed / implemented. That can be either due to lack of time of the developer or other viability considerations.

To give users some idea as to whether a fix has made it to the release repository, the maintainer should either mention the intended release version while closing the issue report, or setup milestones for every minor release and tag the issue report with the next milestone. This will make the issue self-contained in determining whether a fixed release is available to the user.

When you find a bug, open a ticket. When you want a feature, open a ticket. Emails or posting on answers.ros.org or the mailing list are more likely to get lost. It's far less likely to be forgotten if there's a ticket.

If you are unsure for which package the issue should be filled or if an issue you are facing is actually a bug please ask on answers.ros.org first.

Code layout

ROS code is organized into packages, and packages can be collected into a single repository. Packages are represent units of code that you build

Especially if using GitHub it is recommended to create a README.md at the root of your repository to explain to users what to find in the repository. It is recommended to link to the package documentation on the ROS wiki for the contained packages. See this article for formatting help.


The ROS package and build system relies on manifest.xml files.

Here is a template you can fill in for roscpp nodes:

  <description brief="BRIEF DESCRIPTION">
  <depend package="roscpp"/>

And here is one for rospy nodes:

  <description brief="BRIEF DESCRIPTION">
  <depend package="rospy"/>

GUI toolkits

We have migrated all new GUI development to rqt, a Qt-based GUI framework for ROS. Much of the existing code that were built before fuerte used wxWidgets, which has not maintained good cross-platform compatibility. Please consider using rqt for any new GUI development. Development instruction (including license consideration when writing in python) is available there.


The basic build tool is CMake (more).


ROS is an Open Source project. We aim to support a wide variety of users and developers, from grad students to entrepreneurs.

Under the Berne Convention, the author of a work automatically holds copyright, with or without a formal statement to that effect. However, making copyright explicit is helpful in long-term project management.


All standard debugging tools work within ROS, including but not limited to:

General advice:


We use two level of testing:

We have established best practices and policies for writing and running tests.

If you are developing in the ros, ros-pkg, or wg-ros-pkg repositories, a build farm is set up to regularly test the build and run automated tests on a variety of architectures. If the build or tests stop working after one of your commits, you will get an email informing you of the error and will be expected to fix it. See the AutomatedTesting guidelines for more details.



The standard process for releasing code to the ROS community is described on the release page.



As soon as there are users of your code, you have a responsibility not to pull the rug out from under them with sudden breaking changes. Instead, use a process of deprecation, which means marking a feature or component as being no longer supported, with a schedule for its removal. Give users time to adapt, which is usually one release cycle, then do the removal.

Deprecation can happen at multiple levels, including:

Large data files, Large test files

Large files (anything over 1MB, really) often don't belong in development repositories, especially if they are just used for unit tests. These large files affect the time that it takes to checkout the repository, whether or not someone is building your package.

Large data files should be hosted in a public web hosting site. You can also just place the file you need on a web server. Hosting for some files can be provided at download.ros.org. Please start a thread in the Release category on ROS Discourse to request uploading something. You're encouraged to search around if there are files that satisfy your need, before you'll open a upload request.

To download this file for building, use the catkin_download_test_data. OR if you're in older rosbuild era, rosbuild_download_test_data(URL MD5SUM) macro. For example:

    MD5 01603ce158575da859b8afff5b676bf9)

rosbuild_download_test_data(http://code.ros.org/svn/data/robot_pose_ekf/zero_covariance.bag test/zero_covariance.bag 0a51b4f5001f446e8466bf7cc946fb86)

2017-09-23 12:17