Skip to content

Latest commit

 

History

History
167 lines (113 loc) · 7.74 KB

CONTRIBUTING.md

File metadata and controls

167 lines (113 loc) · 7.74 KB
Raw

This repository acts as an index for the ROS distributions. If you would like to add a package to the index you can either index it for just documentation, for binary builds or continuous integration tests. This repository also holds the rosdep rules.

Binary Releases

If you would like to add a package for binary release please see the Bloom documentation. Bloom is a tool which will help you do the release as well as open a pull-request for you. It will also assist adding documentation and source entries. There are several helpful tutorials which provide instructions on how to do things like make a first release.

Documentation Indexing

If you just want to submit for documentation indexing only this tutorial will get you going.

Continuous Integration Indexing

If you would like to index your package for continuous integration tests you can add a source entry in the same way as the documentation index.

The version field is required to be a branch name. This is due to the Jenkins Git Plugin that will always trigger if a repository has changed. After querying Cloudbees support they replied with:

The git plugin is configured to build for a tag / sha1 will always trigger a build.

As such the CI on this repository will enforce that the source version is a branch to not cause continuous triggering of builds. Also of note is that a tag has priority over a branch with the same name so a tag with the same name as the branch cannot exist either.

rosdep rules contributions

This repository also holds the rosdep keys. There is a guide for submitting rosdep keys here. Updates to rosdep rules require the review of two people. This will usually means that it needs a +1, and then it can be merged by a different person.

For convenience in reviewing, please comment in the PR with links to the web listings of packages such as on http://packages.ubuntu.com, http://packages.debian.org, and https://apps.fedoraproject.org/packages or if a pip package pypi.python.org.

Please also briefly describe the package being added and what use case you want to use it for. It's valuable to have a record of the packages as submitted and their intended purpose for clarity in the future so that if there's a conflict there's information to fall back on instead of speculation about the original use cases.

Guidelines for rosdep rules

  • Native packages are strongly preferred. (They are required for packaging and have upgrade and conflict tracking.)
  • Please use the smallest notation possible. For example if an ubuntu package is the same for all versions only write the generic ubuntu rule, don't call out the same package name for every version of ubuntu. Similarly don't call out indirect dependencies or default options for packages.
  • Python packages should go in the python.yaml.
  • Homebrew into osx-homebrew.yaml.
  • If a package is only available via pip use the -pip extension.
  • Supported Platforms
    • Rules can be contributed for any platform. However to be released they must be at least cover the supported platforms in REP 3: http://www.ros.org/reps/rep-0003.html So:
    • Ubuntu and Debian are top priority.
    • Fedora and Gentoo have packaging jobs and should be filled in if they are available.
    • OSX is also nice to have.
    • If specific versions are called out, there should be coverage of all versions currently targeted by supported ROS distros.
    • If there's a new distro in prerelease adding a rule for it is fine. However please don't target 'sid' as it's a rolling target and when the keys change our database gets out of date.
  • Keep everything in alphabetical order for better merging.
  • No trailing whitespace.

Expected Rosdep Sources

Keys in the rosdep database are required to come from packages contained in the following repositories only.

Ubuntu

Debian

Fedora

  • Fedora Project Repositories: release or updates

RHEL/CentOS

  • CentOS Repositories: base, extras, centos-sclo-rh, or updates
  • Fedora Project Repositories: epel

MacOS

TODO

Gentoo

  • Gentoo Portage Repository (e.g. rsync://rsync.us.gentoo.org/gentoo-portage)
  • ROS-Overlay: https://github.com/ros/ros-overlay

If the ebuild you are referencing is not in either of those locations, please file a PR into ROS-Overlay to add it and any needed dependencies to the tree.

Arch Linux

Packages must be in the official Archlinux core, extra, or community repositories at the time they are contributed.

Packages in the AUR may not be added directly. Work has been proposed to add a separate installer for AUR packages ros-infrastructure/rosdep#560.

Alpine Linux

  • Alpine Linux requires the edge release and testing aports branch.

FreeBSD

  • FreeBSD project pkg repository: main or quarterly
  • A database of FreeBSD packages is available at https://freshports.org

pip

For pip installers they are expected to be in the main pypi index.

Python 3 rules

When adding rules for python 3 packages, create a separate entry prefixed with python3- rather than python For example:

python-foobar:
  debian: [python-foobar]
  fedora: [python2-foobar]
  ubuntu: [python-foobar]
...
python3-foobar:
  debian: [python3-foobar]
  fedora: [python3-foobar]
  ubuntu: [python3-foobar]

You may see existing rules that use _python3-suffixed distribution codenames. These were trialed as a possible style of Python 3 rules and should not be used for newly added definitions.

How to submit pull requests

When submitting pull requests it is expected that they pass the unit tests for formatting. The unit tests enforce alphabetization of elements and a consistant formatting to keep merging as clean as possible.

To run the tests run nosetests in the root of the repository. These tests require several dependencies that can be installed either from the ROS repositories or via pip(list built based on the content of .travis.yaml:

Dependency Ubuntu package Pip package
catkin_pkg python-catkin-pkg catkin_pkg
github python-github PyGithub
nose python-nose nose
rosdistro python-rosdistro rosdistro
ros_buildfarm python-ros-buildfarm ros_buildfarm
unidiff python-unidiff (Zesty and higher) unidiff
yamllint yamllint yamllint

There is a tool rosdistro_reformat which will fix most formatting errors such as alphabetization and correct formatting.

Note: There's a known issue discovered here that most tests won't run if you have the python package nose-unitttest installed.