- Development Practices
- Best Practices
- ROS Users Mailing List
- Special Interest Groups Mailing Lists
- Create Your Own *-ros-pkg Repository
- Sharing with Others
- Staying Up-to-Date with Current Development
- ROS Enhancement Proposals (REPs)
- Contribute Patches and Close Bugs
- Participating in Software Reviews
Please see the ROS Developer's Guide.
Please see ROS Best Practices.
ROS Users Mailing List
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.
#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 email@example.com:my_github_name/rosdistro.git
- In your copy of the rosdistro repository browse to the distribution directory you'd like to update.
- 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.
- 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.
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:
Some exemplars of good wiki documentation:
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.
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:
There are a few ROS related hosting sites.
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 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
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.
There are several GitHub organizations which host many of the core ROS packages.
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:
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.