Overview

Even though ROS does not mandate package developers to utilize any specific version control system (VCS) (e.g. git, svn, hg, cvs, bzr), bug/issue tracker, or hosting service, as of 2012 there are now recommended guidelines for all of these things. There are several reasons for doing this:

• Users/developers only need to know a single tool and single place to look for the majority of ROS code.
• Makes the codebase [appear] more homogeneous so that it is easier to navigate (think of the way Wikipedia makes all information homogenous in the consistency of its article layout)
• Manage patches/merges/pull requests in a single place.
• Manage issue/bug tracking in a single place.
• Foster developer communication across all of the ROS community in one place. Most importantly these guidelines unify the ROS codebase and community
• Outsource hosting to a reliable hosting service

Recommended Guidelines

The recommended guidelines are based around two key technologies:

• git - a very popular distributed version control system

• GitHub - a web-based/cloud hosting service for git projects. GitHub has quickly become the dominant hosting service for open source projects and is tightly coupled with git.

Motivation

The reason for the shift to git and GitHub is driven by several reasons deriving from the bullets in the overview above.

• Multiple VCS Tools - A plethora of source control systems made sharing code difficult

• Scattered Bug trackers - In the past we have dealt with multiple instances of bug trackers (e.g. trac, bugzilla) that were not uniform across packages.

• Poor Speed and Uptime - ROS has gone through many VCS hosting services, both external (SourceForge) and internal (code.ros.org, kforge.ros.org) and they have all had severe drawbacks. The main problem behind all these systems was that they were slow and clunky with frequent service outages.

• Maintenance Overhead - As code.ros.org and kforge.ros.org were maintained by the core ROS team, it provided significant maintenance overhead.

• Hard to Work with Community - It was hard to incorporate feedback and patches from the community due to the heterogeneous nature of VCS tools, hosting services and bug trackers.

git

ROS has standardized on git as the preferred VCS. One of the main reasons git was chosen is that it's a distributed version control (DVCS) system which tends to work better in large scale, distributed code development (in contrast to a centralized version control system (CVCS) such as Subversion or CVS). By using git, forking and merging code is a very natural feature and makes it easier to merge patches from contributors. DVCSes also allow one to work offline without needing connectivity to the central server. This is extremely handy when there is server downtime.

GitHub

One may ask why git was chosen over other distributed source control systems such as Mercurial (hg) or Bazaar (bzr). On its own, git has roughly the same (if not more) functionality as its rivals. However, one of the strongest reasons we have standardized around git (as have many others) is because of the GitHub platform.

GitHub is a hosting service for git projects. GitHub has quickly become the dominant hosting service for open source projects and is tightly coupled with git. GitHub is now the official hosting site of core ROS packages and ROS guidelines HIGHLY recommend you move your repositories there.

GitHub was chosen because it is:

• Very fast - Unlike its predecessors such as SourceForge, code.ros.org, and kforge.ros.org, GitHub is blazing fast

• Unmatched Uptime - As GitHub is by far the most popular hosting site, it has excellent uptime and very rare outages. Even with the occasional outage it's not a big deal as git is a DVCS.

• Aesthetically Pleasing - Clean and simple interface

• Code browser - The code browser renders very clean and easy to read code. There is syntax highlighting for virtually every programming language out there with pleasant color choices. There are also nifty features such as being able to make minor edits from within the code browser itself.

• git Simplified - Simplifies many git operations by making them GUI options (e.g. single click merge)

• Pull requests - people can contribute patches without having write access to a repository and maintainers can easily review and merge. Contributors simply fork the repository with one click, clone the repository, make changes, push them back, and then hit the "pull request" button. The owner of the original repository will then be informed of the request, can make comments before merging, and when finally ready, the pull request changes can [usually] be merged with a single click!

• Project management - Features such as milestones and repository/developer analytics make it easier for project managers to make sure development is progressing smoothly and on track.

• Superb issue/bug tracking - GitHub's issue tracking is very simple, intuitive, and not overwhelming.

• Social coding - GitHub's motto is "Social Coding" -- what this means is that GitHub provides tools to allow developers to communicate better and share code/fixes more easily.

• API - GitHub provides a full API to access any of GitHub's features if the current set is not sufficient.

• Active development - GitHub is very well-funded and actively developed with new features showing up all the time.

• No Proprietary Lockin - As all GitHub data, including bug reports and project, are stored in a git repository, mvoing your data is very easy.

• Private repositories - Open repositories are free, but private ones can be purchased at very cheap prices.

• Much much more - GitHub is quite revolutionary as a VCS platform and more than just remote hosting for code. Try it out if you haven't!

GitHub Organizations

Package repositories on GitHub are organized across several GitHub organizations. These allow related packages to be grouped together.

See RecommendedRepositoryUsage/CommonGitHubOrganizations

Migration Help

See RecommendedRepositoryUsage/MigrationHelp

Repository Best Practices

The following are recommended practices with your GitHub-hosted ROS packages.

Commits and Pull Requests

• Only give write access to trusted developers on your package. Other contributors should utilize GitHub pull requests.

• Try to keep your commits as fine grain as possible. If you make various changes each addressing a different problem/enhancement, make a commit for every distinct issue.

• When committing issues to a repository containing more than one package/project/tool/application/library, prefix your commit message with the project name. For example, ros_comm contains the package roswtf, a commit for this could look like:

roswtf: Fixed performance issue when checking package manifests.

• When committing a new release, commit the package.xml version changes as the last change and set the commit message to be just the new version number. This way in the commit log it is very clear where new releases happen.

Issue/Bug Tracking

• If you have an issue with a particular package, go to its issue tracker on GitHub or wherever it's hosted and post the issue there.

• If you're not sure which package the issue belongs to, post a question at http://answers.ros.org for further guidance.

Conclusion

Please follow the guidelines as closely as possible. This will ensure smooth integration with the ROS ecosystem at both the code and community levels.