This page describes the current packaging practices for Ruby in Debian. For more general information, see this wiki page.

This page is quite disorganized, and some of it was written as a "plans for Ruby in wheezy page", not as a general documentation for packaging. Please do not hesitate to improve this page. Another effort to document the workflow of packaging ruby-gems for Debian is made by the debian-diaspora Team at: this wiki page , which is focused at beginners and very detailed.

Joining the pkg-ruby-extras team

We always welcome people to help us out. If you want to, please follow the following guidelines.

Using Git

We use git together with myrepos (Multiple Repository management tool) to track the git repositories for each package.

Before you continue, ensure you have installed the tools used by the team:

apt-get install myrepos git-buildpackage pristine-tar gem2deb

Git workflow

The following workflow is used for (almost) all non-native packages maintained by the Ruby team:

Obtaining the master repository

git clone ruby-team

To obtain one of the packages, do:

cd ruby-team
./checkout $PACKAGE

If you want to obtain all of the team packages (have in mind that the team has a lot of packages, so this will probably take a little long), do:

# look at .mrconfig
mr --force checkout

To clone all team packages with parallel checkouts, use

mr --force -j 5 checkout

To avoid typing your username and your password see this ?page.

Creating a new Git repository and pushing an existing package to

Note: please do not leave empty repositories on salsa; only create a repository there just before pushing your package.

Suppose you want to package the latest 0.7 version of the foo Ruby gem, to obtain a ruby-foo package. See the naming conventions for packages.

On your local workstation:

cd ruby-team

Packaging new gems from scratch

Note: See Teams/Ruby/Packaging/gem2deb if you are new to ruby packaging

On your local machine, get a basic .dsc from the library you want to package, using:

gem2deb foo

gem2deb will then try to download the foo gem from, and convert it to a primitive Debian package ruby-foo_0.7-1.dsc. You can also run gem2deb on a local .gem file foo-0.7.gem or a tarball (e.g. from Github).

At this point, please do not make any change to the package generated by gem2deb. It is important to track all the changes in git. Then:

cd where-you-cloned-pkg-ruby-extras.git
./update-mrconfig # will generate the config for your new repo
./checkout ruby-foo # will clone your new repo
cd ruby-foo

gbp import-dsc --pristine-tar path-to/ruby-foo_0.7-1.dsc
git tag -d debian/0.7-1 # because the package is not ready yet
git push --all
git push --tags

Then, make the needed changes to the packaging, and then

git push

After upload, tag the package with

git tag debian/0.7-1

And don't forget to

git push --tags

Known Issues

If mr checkout gives an error like mr: illegal section "[DEFAULT]" in untrusted:

Add .mrconfig path to ~/.mrtrust

If your local username is different from your Alioth username (that's probably the case for non-DD developers with -guest accounts), add the following to your ~/.ssh/config:

User alioth-username

Handling patches on upstream code

If the package you are working on includes upstream patches (i.e. debian/patches/*), you need to make sure that the Git repository is in a sane state after build (i.e. no uncommitted changes to the work tree).

Since 1.16.1, dpkg-source unapplies by default patches that have been applied during --before-build. For earlier versions, it is possible to force this behaviour by adding the unapply-patches option to debian/source/local-options (source: blog post by Raphael Hertzog)

$ echo "unapply-patches" >>debian/source/local-options
$ git add debian/source/local-options
$ git commit -m "Unapply patches after build"


Guidelines for Ruby packaging

gem2deb as the preferred packaging tool for ruby software

gem2deb is the current packaging tool for Debian Ruby packages. It:

It serves two goals:

gem2deb can be considered to some extend as the reference implementation of the Debian Ruby policy.

Single package for all Ruby versions

Since Wheezy, Ruby software must not come in separate packages per Ruby interpreter version, as we did until Squeeze (libfoo-ruby1.8, libfoo-ruby1.9.1 etc). We use a single binary package per source package no matter what. In the case of native extensions, those single binary packages will contain the compiled extensions (*.so) for all supported Ruby versions. This is supported by gem2deb, so you should use it.

Naming of ruby packages

The libfoo-ruby naming is deprecated.

The guidelines are the following:

Handling of shebangs

Ruby applications should use /usr/bin/ruby, and depend on ruby | ruby-interpreter.

gem2deb currently does the following:

Values of XS-Ruby-Versions

The XS-Ruby-Versions values match the name of the ruby interpreter, or all if the package is supposed to work with every supported version of the interpreter.

For Wheezy, supported values were:

For Jessie, only one version of the interpreter is included. The valid values are:

For Stretch, only one version of the interpreter will be included. The valid values are:

When more ruby interpreters will be added, the list will be expanded.

Switching to github tar and other changes to orig-source

see this page

Guidelines for Packaging Ruby on Rails Applications

Requesting Sponsorship

Once your package is ready (or at least, once you think it is), a DD will have to review your changes and upload it to the archive. It is important to understand that reviewing and sponsoring packages is a tedious process, and that most DDs would prefer to do something else instead. So, make sure that you make the best possible use of their time, so they will be happy to sponsor you again. :-)

First, make sure that your package is really in good shape. That means answering at least the following questions:

Once your package is ready, you must:

Subject: RFS: ruby-foo 1.2-1, ruby-bar 2.0-1


The following packages are ready to be uploaded (I also verified the
points listed on

Could you please sponsor them?

 ruby-foo 1.2-1
 ruby-bar 2.0-1

Thank you!

Tasks for team-maintained Ruby packages

Updating a package to a newer version

If you have a working debian/watch file (check by running uscan --verbose --report), you can simply import a new version with

gbp import-orig --pristine-tar --uscan

Alternatively, you can fetch the most recent version of a gem, and make a tarball out of it

gem2tgz <gemname>

where <gemname> is the upstream name of the gem, or run gem2tgz on a local .gem file. You can also get a specific version and then create the tgz by doing

gem fetch -v <gemname>
gem2tgz <gemname>.gem

Then import the created tarball in the Git repository with gbp import-orig --pristine-tar.

Now update your packaging in the master branch. Once you are done, push the branches and the tags to the team repository

git push --all
git push --tags

Install the package and see if all dependencies are satisfied for rubygems integration by creating a Gemfile for the library and running bundle install --local.

$ echo "gem '<library name>', '<version>'" > Gemfile
$ bundle install --local

See steps of updating rails apps like diaspora, gitlab and redmine

Updating packages with API breaking changes

Read this transitions primer if you are new to handling transitions.

At least compliance should be assumed (even though many upstreams don't follow it and breaking changes are introduced in even security updates, for example rack 2.0.7 -> 2.0.8 is not compatible) as a compromise (as assuming every change breaks is not practical). This means major version updates of upstream with public API (when version >= 1.0) and minor updates of upstream without a public API (when version < 1.0). For example ruby-method-source update from 0.8 to 1.0 and pry update from 0.12 to 0.13, both are breaking changes (sometimes we may be lucky and nothing breaks, but we cannot assume that when upstream explicitly gives a warning by appropriate version bumps).

When uploading such API breaking changes these steps must be followed,

  1. Verify autopkgtests of all reverse dependencies and rebuilds of all reverse build dependencies are passing. Use Packaging/ruby-team-meta-build; or upload to experimental and watch the britney pseudo-excuses for experimental

  2. There are two paths you can take for uploading to unstable,
    1. Ideally all breaking packages should be fixed before uploading to unstable. Fixed packages should be uploaded along with the package that introduced API breakage.
    2. Upload to experimental and file bug reports with severity important against all failed packages. It is a good idea to document the list of packages that failed in debian/changelog. Give sufficient time for the maintainers (at least a week for simple fixes or more for complex changes) to fix the broken packages.
  3. When all the broken packages are fixed or the provided time is passed, upload to unstable along with all the fixed packages. Add Breaks for all the packages that failed. The bugs against unfixed packages should be raised to serious.

Exceptions (be careful with minor updates also/minor updates broke API in the past): rails, ruby-rack, ruby-doorkeeper, ruby-devise, ruby-graphql, ruby-grape

Note: Bigger transitions like ruby or rails may need collaboration from the whole team and new versions may be uploaded to unstable and broken packages may be fixed later. Try to coordinate with the team on the mailing list.

Howto: converting a package from ruby-pkg-tools to gem2deb

This section describes how to convert the libfeedparser-ruby package to gem2deb. That package is simple, but still gives a good overview of the process. Please improve this section with your own experience.

  1. Get the libfeedparser-ruby source package. (apt-get source libfeedparser-ruby)
  2. Find the name of the rubygems on It is ruby-feedparser.
  3. Run gem2deb ruby-feedparser. This generates a basic (but working) source package.
  4. Cd to ruby-feedparser-0.7/
  5. Copy the changelog entries from the libfeedparser-ruby source package to debian/changelog
  6. Generate the templates for transitional packages: run gen-ruby-trans-pkgs libfeedparser-ruby > /tmp/templates. Edit debian/control: the Replaces, Breaks, Provides go to the ruby-feedparser binary package, and the other binary packages need to be added at the end of debian/control.

  7. Fill-in debian/control: description, homepage, build-dependencies, ...
  8. Copy debian/copyright from libfeedparser-ruby, and review it. It is a good idea to use that opportunity to convert it to DEP5.
  9. Edit
  10. Find how the test suite needs to be run, and edit debian/ruby-tests.rb accordingly. There are many examples in the packages maintained by the pkg-ruby-extras team.
  11. Build the package, make sure everything works (build in a clean chroot, run lintian, etc, etc).
  12. Import it into the pkg-ruby-extras git repository.
  13. Ask for review and sponsorship.

Renaming existing packages using the old naming convention

Existing packages must be renamed to the new scheme. This renaming must be done using the standard Debian practices (i.e. Debian Developers' Reference, section 5.9.3). In our case, this means:

Removing transitional packages

For packages that have been renamed before the release of Wheezy from the libsomething-ruby* scheme to ruby-something, all transitional packages libsomething-ruby* can be removed for Jessie, after checking that they have no more reverse (build-)dependencies.

For packages that have not yet been renamed by the Wheezy release, the transitional packages must remain in place until after the Jessie release.

Packages with transitional packages to be dropped have bugs reported with the usertag ruby-policy-remove-transitional-packages.

Enabling autopkgtest

Since version 0.9, gem2deb has gained support for autopkgtest. See this message to the debian-ruby mailing list for more details on how to activate and configure the test suite for autopkgtest.

Check and fix location of rubygems-integration files

Some packages do not have a new version but still need to be reuploaded, because the rubygems metadata are installed in an obsolete directory (e.g /usr/share/rubygems-integration/1.8). Tracking and fixing packaging with files in /usr/share/rubygems-integration/{1.*,2.0} is needed before Jessie freeze. Use apt-file to find those packages, and if no new upstream version is available, refresh the packaging and reupload.

Multiple gemspec files

You can create debian/gemspec as a symbolic link to the gemspec file you want to use. You can also set DH_RUBY_GEMSPEC variable in debian/rules. For autopkgtest, you should remove the Testsuite field in debian/control and create debian/tests manually.

Example packages: ruby-concurrent, ruby-flipper, ruby-elasticsearch

Handling Rails Engines

See Teams/Ruby/Packaging/RailsEngines

PackageManagement CategoryPackaging