Guidelines for Ruby packaging (Archived)

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:

Binary packages must normally be named "ruby-foo". If the package is mainly used as an application (not as a library), then it can be named "foo". Known examples are rails, chef, bundler, puppet.
Source packages must have the same name as the "main" binary package. (our infrastructure is better at handling this case)

Handling of shebangs

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

gem2deb currently does the following:

If the XS-Ruby-Versions field contains 'all', all shebangs of programs installed to /usr/bin are rewritten to /usr/bin/ruby
If several versions of the interpreter were supported by gem2deb (as it was the case for Wheezy), all shebangs of programs installed to /usr/bin would be rewritten to the binary corresponding to the first version listed in XS-Ruby-Versions. For example, is XS-Ruby-Versions is ruby2.1, ruby2.2, all shebangs would be rewritten to /usr/bin/ruby2.1

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:

all
ruby1.8
ruby1.9.1

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

ruby2.1
all

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

ruby2.2 (temporary in unstable)
ruby2.3
all

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

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.

Get the libfeedparser-ruby source package. (apt-get source libfeedparser-ruby)
Find the name of the rubygems on rubygems.org. It is ruby-feedparser.
Run gem2deb ruby-feedparser. This generates a basic (but working) source package.
Cd to ruby-feedparser-0.7/
Copy the changelog entries from the libfeedparser-ruby source package to debian/changelog
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.
Fill-in debian/control: description, homepage, build-dependencies, ...
Copy debian/copyright from libfeedparser-ruby, and review it. It is a good idea to use that opportunity to convert it to DEP5.
Edit ruby-feedparser.docs
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.
Build the package, make sure everything works (build in a clean chroot, run lintian, etc, etc).
Import it into the pkg-ruby-extras git repository.
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:

when libfoo-ruby gets renamed to ruby-foo, then ruby-foo must declare Provides: libfoo-ruby, Replaces: libfoo-ruby and Breaks: libfoo-ruby
when libfoo-ruby1.8 gets renamed to ruby-foo, then ruby-foo must declare Provides: libfoo-ruby1.8, Replaces: libfoo-ruby1.8, and Breaks: libfoo-ruby1.8
when libfoo-ruby1.8 and libfoo-ruby1.9.1 are turned into a single pure-Ruby package ruby-foo, then it must declare Provides: libfoo-ruby, libfoo-ruby1.8, libfoo-ruby1.9.1, Replaces: libfoo-ruby, libfoo-ruby1.8, libfoo-ruby1.9.1, and Breaks: libfoo-ruby, libfoo-ruby1.8, libfoo-ruby1.9.1
ruby-foo must also provide transitional binary packages for libfoo-ruby, libfoo-ruby1.8 and libruby1.9.1 (when it's the case). You can use the gen-ruby-trans-pkgs script to generate the proper snippet to be added to your debian/control.
note that this is only needed for packages that were already released with Squeeze. New packages must not keep any references to packages named as lib*-ruby.
According to Renaming_a_Package the old source package will be removed automatically after the renamed package enters the archive. If that doesn't happen after a reasonable amount of time, please request the removal of the old package.

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.

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.

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.

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"

References

Documentation from the Games team which share much of the workflow

TeamsRubyPackagingArchive