This page is designed to provide a guide for package maintainers. It will include an overview of the roles and responsibilities of a package maintainer as well as provide some checklists which maintainers can follow.

• A lot of this information is drawn from Roles and Responsibilities of Package Maintainers presented at ROSCon 2013 slides and video of that presentation are available.

Purpose of a Maintainer

The purpose of maintaining a package is to ensure that the package is available to the community by releasing it with bloom and to support the package by servicing pull requests and acknowledging issues, but not necessarily addressing issues. The maintainer provides a point of contact for the community to keep track of the state of the package. This is a very important role as it provides access to the current development for the whole community.

Role of a Maintainer

• Release the package and deploy them to the build farm using bloom.

• Review pull requests and merge them if they are appropriate and pass unit tests.
  • A maintainer should push back on any patch submitter if the patch is not up to their standards.
  • Periodically release the package, in order to propagate the pull request changes to the public debs.
• Provide responses in the bug tracker even if it's just to say, there's not developer time for this right now.

• It is 'not' doing active development.

  • However a maintainer can also be a core developer which is doing active package development.

Responsibilities of a Maintainer

Maintainership is declared on a per Distribution basis. This gives a clear time scope on the commitment for being a maintainer. When allocating maintainership positions, priority will be given to past maintainers for continuity. The duties of a maintainer should be a couple hours per Distribution. These are some of the responsibilities of a maintainer:

• Moderating the issue tracker, this includes
  • Responding to issues, even if it is just to say we don't have time to fix this
  • Reviewing, requesting changes to, and merging patches or pull requests

• Releasing the package with bloom for the distribution you are a maintainer for

  • This includes re-releasing after patches/fixes have been applied, and ensuring that the fixes which are released do not disrupt the distribution (API and/or ABI compatibility).
• Monitoring and updating the documentation.

Perks of Being a Maintainer

By being a maintainer for one or more packages you are helping the community stay up-to-date and more useful for others. Additionally, you gain recognition as a contributor to a package which many others likely use. Finally, you get some influence on the direction of a package. Since you will be helping service pull requests and issues, and will likely have an opportunity to help with development, you get the chance to steer the direction of the development such that it better suits your needs. With that being said, you should avoid ignoring other use cases and users, this process works best when we can collaborate on packages rather than encouraging people to fork off new packages because they could not use the common one.

Terminology

There are some terms in common usage when maintaining a package.

Repositories

The upstream repository is the main repository where the code for the package is stored and worked on. This is the repository on which issues and pull requests will be opened. The release repository is a separate repository that contains metadata useful for doing releases of the upstream repository into ROS. Almost all existing packages already have a release repository. The rosdistro repository contains a master list of which packages are available in which ROS distribution.

Distributions

There are two concepts of distribution in ROS. The first is the ROS distribution that contains the ROS packages. The second is the Linux distribution that a ROS distribution is released for. Each ROS release is built for one or more Linux distributions that is decided upon at the release time of the ROS distribution.

Current Maintenance Status

A summary for each Distribution can be found at http://repositories.ros.org/status_page/

Understanding the repositories.ros.org status_page

There is a lot of information on the repositories.ros.rog status page, so this is a short walkthrough of what some of that information means. For this example, click here.

The main status page for a ROS distribution shows every released package. To see just the packages you are interested in, you can use the text box in the top left (the text box is a simple search, no globbing or regex). For each line below the search text, there are a number of fields:

• Name - The name of the binary package
• Repo - The source repository the package comes from (many packages can come from one repository)
• Version - The currently released version
• Status - Whether the package is currently maintained
• Maintainer - Who the current maintainer(s) is
• Xsource, X64, X32, etc - The last few columns show the Linux distributions that this package is available for, in a very shortened manner. For instance, Ssource means "Ubuntu Saucy" source build. S64 means "Ubuntu Saucy" 64-bit x86 build, etc.

  • For each column, there are 3 boxes below it, describing the state of the package in the "building", "testing", and "main" repositories. The "building" repository is the latest unstable build. The "testing" repository is an automatically synced version of the successful builds from the "building" repository; maintainers will sometimes ask people to test a package from the "testing" repository. Finally, the "main" repository is the package released into the distribution. Promotion from the "testing" repository to the "main" repository is manual, and is done on a semi-regular basis. More information on the testing repository is available here.

  • There is a legend in the top middle of the screen that explains what the colors of the boxes means.
  • There are a number of tooltips available on the repositories.ros.org site which will show up when hovering over certain elements.

Understanding the CI (Continuous Integration) build farm

All packages listed on repositories.ros.org are backed by a number of jobs on the backend build.ros.org. There are thousands of these jobs, each one automatically generated when a new package is added to the ROS distribution. Each job follows the same basic short name as described in the #repos section. This is where you can find information on why a job is failing, what the current status of the jobs are, etc. This is also a place to find out what downstream packages are dependent on your package, though the main package page on wiki.ros.org is more convenient.

Claiming Maintainership

If you find a package which you maintain but does not have the maintenance status set, set it in the release file (here , for hydro). See: http://reps/rep-0141.html#distribution-file

If you find a package which you do not maintain and the maintenance status is not set, and you are interesting in helping to support it, then you should try these things in order:

• Contact the listed maintainer, ask him/her if they will be maintaining this package(s) for this distribution.
  • If so, you can offer to help by being a co-maintainer
  • If not, you can offer to help by taking over maintainership
  • Both options usually require the maintainer to give you access to the upstream repository

• If the current maintainer cannot be reached, send an message on the ROS Discourse Release Category

  • This mailing list can help you figure out how to resolve the maintenance status without the currently listed maintainer.

If you are listed as a maintainer for a package, but you cannot maintain it for this distribution, you should try these things:

• Contact people who have contributed to the package in the past with issues or pull requests to see if they would like to help.

• Send an message on the ROS Discourse Release Category, and ask for help.

Checklist For Package Maintainers

For each package that you maintain please make sure the following has been completed:

• Make sure the package is released into the target Distribution, in these examples the target distro is Hydro.

  • You can check this by seeing if it is in the hydro/distribution.yaml file and has release information

  • If not, you need to release the repository, which the package is in, using bloom

  • Make sure there is a maintenance status on either the repository or package level in the distribution file, see: http://reps/rep-0141.html#distribution-file

  • The status of the Debian packaging is listed here: http://repositories.ros.org/status_page/

• Make sure the package's repository has a source entry in the distribution file

• Make sure the package's devel job is succeeding without warnings / failing tests

  • The devel jobs are listed here: http://build.ros.org:8080/view/Kdev/

  • It's recommended to also setup pull request jobs for reviewing changes.

• Make sure the package has a wiki page and that the header information is up to date.

• Make sure the package's repository has a doc entry in the distribution file

  • Having an entry here creates a documentation job on the build farm for this repo
• Make sure the package's doc job is succeeding without warnings

  • The jobs and are listed here: http://build.ros.org:8080/view/Kdoc/

For catkin packages/repositories

• Common mistakes in catkin should be corrected:

  • Run catkin_lint to identify many common errors

  • Make sure to wrap all test related CMake code in an if(CATKIN_ENABLE_TESTING) check

  • Make sure that your packages are using catkin_EXPORTED_TARGETS correctly

  • Make sure that your packages have CHANGELOG.rst files

  • Make sure that your packages are using <run_depend> or <build_export_depend> correctly for transitive build dependencies. If in doubt, convert to package format 2 where the distinction is clearer.

• Release their package(s) for hydro using bloom
• Set maintenance status for your packages

Tutorials

How to make a release

See the bloom/Tutorials

How to submit a repository for documentation

• TODO merge from here: rosdistro/Tutorials/Indexing Your ROS Repository for Documentation Generation

How to submit a repository for continuous integration

• TODO

How to host software

• See the Recommended Repository Usage