Development Practices

Please see the ROS Developer's Guide.

Best Practices

Please see ROS Best Practices.

ROS Users Mailing List

The ros-users mailing list: ros-users@code.ros.org is the primary mailing list of the community. Subscribe here View the archives

Special Interest Groups Mailing Lists

In addition to the ros-users list, we also several SIGs which focus on specific subtopics, and help guide development efforts. Please see the SIG summary page for links to the specific ones.

IRC

#ROS on irc.oftc.net. Not an "official" channel... but it is there.

Web Client: http://irc.lc/oftc/ros/yourname (change your nickname)

Create Your Own *-ros-pkg Repository

There are hundreds of ROS repositories hosted by companies, universities, and individuals around the world. Whether you're releasing one ROS package or hundreds, feel free to start your own repository to share your code with the rest of the community.

Please see our RecommendedRepositoryUsage

Visual representation of ROS release workflow is summarized here.

Indexing Your *-ros-pkg Repository for Documentation Generation

Once you've created your own *-ros-pkg repository, you can document your stacks and packages on ROS.org. The steps to have your repository added to our indexer have changed with ROS Groovy. You'll find instructions for both Groovy and later and Fuerte and ealier below.

Groovy and later

• There are a few steps to have your repository added to our indexer:

• First, fork the following repository on GitHub https://github.com/ros/rosdistro

  • More information on forking GitHub repositories: https://help.github.com/articles/fork-a-repo

• Checkout your forked copy of the repository for editing

  • git clone git@github.com:my_github_name/rosdistro.git

• In your copy of the rosdistro repository browse to the distribution directory you'd like to update.

  • cd rosdistro/<DISTRO_NAME>

• Inside of this directory, edit the doc.yaml file and add your repository information (while maintaining alphabetic order of the repositories).

  • Optionally, you repository entry can contain a depends value which contains a list of other repository names listed in this file upon which your code (and it's documentation) depend, but which you do not want to document explicitly in the job associated with your repository.

• Run the following script in the root of your rosdistro checkout to make your file comply to rosdistros special formatting rules. It will change the files in place, so if you want to be extra safe you could back up your changes before.

  • rosdistro_reformat file://$(pwd)/index.yaml

• Verify your changes before commiting the changes

  • git diff doc.yaml

  • git commit -m "Adding my_repo_name to documentation index for distro" doc.yaml

• Push your changes to your remote GitHub repository git push origin master

• Submit a pull request on GitHub to the rosdistro project to add your rosinstall files to the indexer.

• Send an e-mail to ros-users announcing your repository.

• That's it! Once your pull request is serviced, documentation for your rosinstall files will be generated the next time the documentation jobs run.

Fuerte and earlier

• There are a few steps to have your repository added to our indexer:
• Fork and checkout the rosdistro repository as mentioned above
• Instead of updating a single doc.yaml file each entry has its own file in the documentation directory for the distribution you'd like to update.

  • cd rosdistro/doc/<DISTRO_NAME>

• Inside of this directory, create a rosinstall file that pulls the code you'd like to have documented. Something like my_repo_name.rosinstall.

  • Optionally, you may also add an additional rosinstall file with a _depends suffix (so my_repo_name_depends.rosinstall) which contains unreleased packages upon which your code (and it's documentation) depend, but which you do not want to document explicitly in the job associated with your repository.

• Make sure to add your files and commit changes

  • git add my_repo_name.rosinstall my_repo_name_depends.rosinstall

  • git commit -a -m "Adding my_repo_name to documentation index for distro"

• Continue with pushing, submitting pull request and announcing as mentioned above

Pull in changes from upstream

To pull in changes from github.com/ros/rosdistro, you need to add another remote

git remote add upstream https://github.com/ros/rosdistro.git

Now to pull changes other people have made and ROS has commited to github:

git pull upstream

Git will pull changes from upstream and automatically merge them into your current branch. This single step could won't notify you of conflicts between your local repo and upstream. You may have to identify a branch when using this: git pull upstream master

An alternative is a two step process:

git fetch upstream

git merge upstream/master

This two step process will prompt you if there are any conflicts between your local repo and upstream.

Documenting Your *-ros-pkg Repository on ROS.org

Once your repository has been indexed, overnight the documentation jobs are recreated and run.

Once the documentation job has been run you can create a wiki page for you package or stack. To create a page. Enter into the wiki the url of the page you want to create. It will say the page does not exist, select the appropriate Template from the list to create your page. We encourage you to create usage documentation, tutorials, reviews, or whatever other content you want. See the guide to writing package documentation

The following wiki pages have guidelines to help you get started with documenting on the wiki:

• Wiki Style Guide

• Guide to Writing Package Documentation

• Guide to Writing Tutorials

• Guide to ROS.org Wiki Macros

Some exemplars of good wiki documentation:

• tf

• carrot_planner

• actionlib

• ground_station

• velodyne_driver

Sharing with Others

The ros-users mailing list is a great forum for letting others in the community know about your latest creations and updates.

Staying Up-to-Date with Current Development

If you go to the Distributions page, you will see a list of current and future ROS distribution pages. Planning notes for upcoming distributions will be on the relevant wiki page, e.g. Diamondback Planning.

You can also monitor the ROS.org news site for announcements from the community.

ROS Enhancement Proposals (REPs)

The REP process, closely modeled on Python's PEP process, allows the community to participate in the ongoing development of ROS. For more information, see the REPs page.

Contribute Patches and Close Bugs

There is a lot of open tickets in the ROS community. Ones which are looking for new owners are posted on the Handoff List page.

Repositories

To maximize community participation, we follow a federated repository model: rather than having one true place for all ROS packages, users and developers around the world are encouraged to host their own repositories of ROS packages. Each repository can be managed and licensed as desired by the respective maintainer, and the maintainer retains direct ownership and control over the code.

You can setup your own public repository or use free hosting online. To list a few:

• bitbucket.org
• code.google.com
• github.com
• sourceforge.net

There are a few ROS related hosting sites.

code.ros.org

The core ROS packages were originally hosted at SourceForge. When ROS traffic grew too high code.ros.org was setup to host the core ROS software. A list of projects on code.ros.org is available at: https://code.ros.org/gf/project However the use of code.ros.org is now not recommended for new projects and projects are actively being migrated off of this server.

kforge.ros.org

kforge.ros.org was setup as a replacement of code.ros.org with support for more version controls systems and other services. It is continued to be used, though for new projects GitHub is the recommended platform. For a list of projects on kforge.ros.org see: https://kforge.ros.org/projects

GitHub

We recommend using GitHub for hosting. At Willow Garage we have switched to use GitHub as our primary hosting site. The ease of collaboration using the GitHub ecosystem has proven very effective.

Organizations

There are several GitHub organizations which host many of the core ROS packages.

See RecommendedRepositoryUsage/CommonGitHubOrganizations

Participating in Software Reviews

Design and peer review documentation for ROS packages are available online. On every package or stack page, e.g. actionlib, there is a link to 'Reviews' that will show you a list of any API or documentation reviews that have occurred. These review notes generally contain design goals and motivation as well.

To participate in the reviews, you can sign up for the ros-users list here:

https://code.ros.org/mailman/listinfo/ros-users

The general process for a review is:

• Maintainer puts together documentation for review (e.g. documenting APIs, design notes)
• Maintainer creates a new review page for the review that links to the relevant documentation

• A week before the review meeting, an e-mail is sent to ros-users

• Comments are collected in the review page
• Meeting is held where comments are reviewed. If necessary, review process is repeated until approval is reached.

While meetings have generally been held in person, it is possible to have open meetings (e.g. IRC) if people express interest on the mailing list.