Translation(s): none

New upstream Release

How to upgrade to a new upstream version. You can check for it regulary here:

Main workflow

If you got a correct debian/watch file and there are no problems, you can use uscan. First make sure you got a local repository from salsa which has the pristine-tar branch:

gbp clone --pristine-tar<pkg-name>.git

Now use uscan:

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

Note: If you want a different version than latest version, you may have to download it manually or use uscan --verbose --download-version option and run gbp import-orig --pristine-tar separately.

gem fetch -v <version> <gem name> and gem2tgz <gem file> can get you any version of the tarball.

Edit debian/changelog. You can use the following command,

gbp dch -a

Or use dch for it, it will give you a template:

dch -v <new-upstream-version>-1

Replace "UNRELEASED" with "unstable" and insert this as the first entry:

  * New upstream Release

Then try to build the package like usual and make corrections and changes which are needed.

Common problems

import from github

If upstream from rubygems is missing folders (test, spec, README, etc) point debian/watch to github (assuming there is the solution. Often there is the solution. It is a tricky problem. Make a backup of your directory, double check everything. Correct wrong info here. Boutil explained it in IRC, thanks to him.

Go to your build directory,top level and delete all old tarballs, then go in the source folder:

cd ~/Build/build-minimagick
rm -r *tar.gz
cd ruby-mini-magick

Edit the file debian/watch and point it to github. Use this content and adapt the path for github:

opts=uversionmangle=s/(\d)[_\.\-\+]?((RC|rc|pre|dev|beta|alpha|b|a)\d*)$/$1~$2/,dversionmangle=s/\+(debian|dfsg|ds|deb|gh)\d*$// \ .*/v?(\d[\d\.]+)\.tar\.gz

Make sure to add gh for dversionmangle if you copy from somewhere else. Run uscan to test if you got the syntax right, then import the new tarball

uscan --verbose --report

uscan --force-download

and import the upstream version from github

git  import-orig --pristine-tar ../*tar.gz

When you are asked for the version, add +gh to it


and make sure to use it in debian/changelog too, when using dch:

dch -v 3.6.0+gh-1

You may run into further trouble. Try "git tag" (i had to remove the tag pristine-tar, as an example).

Non-Maintainer Upload

If you are not the maintainer of the package but wish to update it, check if it is being maintained in the pkg-ruby-extras team, if so then you can follow the steps listed above to build the package.

When making changes to debian/changelog add the following line :

 * Team Upload

See ruby-configurate for example.

By adding Team Upload, lintian will not give warnings about NMU and NMU version format

Major version updates

When you upload a new version to unstable you should make sure other packages depending on it still works with the new version.

You can use reverse-depends command to find out what other packages depend on your package.

reverse-depends <pkg-name>
reverse-depends -b <pkg-name>

Note:- reverse-depends command is supplied by the package ubuntu-dev-tools

Note: -b option will search for reverse build dependencies

When there is a major version update, like 0.x to 1.x, 1.x to 2.x, 2.x to 3.x etc it means there are breaking changes ie, software that worked with previous version may not work with the new version, some features are removed.

If the other software is not using the removed feature, it may still work, but you should verify it.

It is safe to upload major version updates to experimental first and notify maintainers of reverse dependencies to test.

Add Breaks for any reverse dependency that has a strict requirement for the previous major release in their gemspec.

For example gitlab 11.6.0 needs kubeclient ~> 4.0 but gitlab versions before that needed kubeclient ~> 3.0. So ruby-kubeclient should declare Breaks: gitlab (<< 11.6~)

Compatibility with gitlab and diaspora

We should be careful when an update involves gitlab or diaspora in their reverse dependencies.

apt-cache rdepends ruby-foo

Reason: Declaring tight dependency by gitlab and diaspora (~> x.y.z).

Root cause: There is no guarantee that minor updates won't introduce breaking changes.

Solution: Semantic Versioning.

Way out: We should follow these steps when either gitlab or diaspora appears in the reverse dependency of any update.

  1. If it is a major version update, then it should be uploaded to experimental first. Once compatibility with gitlab and diaspora is tested, it can be uploaded to unstable after relaxing gem dependency in their Gemfiles.
  2. If it is a minor version update and it is development version (>= 1.0), follow step 1 as there is no guarantee that minor versions will not introduce breaking changes.

  3. If the gem follows ?, the upstream guarantees to not introduce breaking changes in minor updates. Check list of upstreams committed to semver first. If an upstream has not pledged ?SemVer complaince, we should ask them to follow it and add it to the list.

  4. Check if the gitlab and diaspora versions in unstable allows the minor update from "Packaging Progress Statistics" at If it allows the minor update (~> x.y), upload the new version to unstable.

  5. If it does not allow, relax the dependency in Gemfile and request upstream to relax the dependency so we don't have to maintain a patch. gitlab has been responsive to such requests, but diaspora has not been.