Ubuntu Wiki

This page helps to choose proper version numbers for packages uploaded in the PPAs related to UME. It also offers general advice that may be useful in other contexts.

Ordering

Incrementing

Versions need to sort properly to allow upgrades. The Version field is covered in the Debian Policy Manual.

It's customary to increment the last part of the version if you're reuploading a changed source into the same repository as it came from.

You can easily compare versions with dpkg's algorithm:

    % dpkg --compare-versions 1.3-2 '<<' 1.3-3 && echo true
    true
    % dpkg --compare-versions 1.3-2 '<<' 1.3-2um1 && echo true
    true
    % dpkg --compare-versions 1.3-2 '<<' 1.3-2~um1 && echo true
    %

(see the dpkg man page for help on the compare-versions flag)

The version of any given package in an archive should never go backwards. The Ubuntu archive and PPAs both enforce this restriction (at least as long as the package isn't deleted). If you manage your own archive, resist the temptation to lift this restriction! Remember that, if the version of a package goes backwards, any users of your archive will not upgrade automatically to the "new" version.

By the same token, you should choose version numbers carefully to avoid painting yourself into a corner later. Is anyone else further "upstream" from you (Ubuntu, Debian, etc.) going to upload the same package, such that you might later want to merge with them? If so, you should anticipate their likely versioning and select version numbers less than what they are expected to use. Version number elements such as "-0", "~" (see below), and namespaces may help with this. Do not assume that developers further upstream from you will accommodate your mistakes; in particular you may well not be able to persuade somebody to add an epoch to their version number just for you.

Do not add an epoch (see the Policy Manual) to your version number unless you are certain that nobody further upstream from you is ever going to upload the same package; even then you should be very sure you know what you're doing. If you add an epoch but a developer upstream from you doesn't, then you'll be stuck merging changes manually for ever more even if they integrate all your changes.

Forking / appending

Usually, when forking, one appends a namespace string; for example Ubuntu forked grub 0.97-29ubuntu18 from Debian's 0.97-29 (and did 8 uploads in Ubuntu).

Backporting

The "~" character is special and allows ordering of a version just before another one; for example 1.3-2~backport12 is a *smaller* version than 1.3-2. This is often useful for backports as you take a source from the next release almost verbatim and put it in the current stable release, but you want people to upgrade to the official (non-backported) source when they actually upgrade to the next release.

To further distinguish between backports, it's customary to list the distribution the backport is aimed at; for example if you backport to gutsy version 1.3-4 from hardy, you could name it 1.3-4~gutsy1 or 1.3-4~710-1 etc.

Each different source has a different version; namespaces

Source identifier

You can take a source from e.g. Debian and put it in Ubuntu verbatim or in a PPA without changing its version number, but if you do change *anything*, change the source version as to uniquely identify your source package. If we didn't follow this rule for Ubuntu, we would be confused when discussing package foo version 1.3-2 because we wouldn't know whose 1.3-2 that is; it would also be terribly confusing when trying to resync between repositories using the same version numbers, but for different things and at different times.

Namespaces

This also implies that you shouldn't use a version number that other people might use in the future; it's best to namespace your version numbers. For example when Ubuntu takes package foo 1.3-2 from Debian and changes it, it will be called 1.3-2ubuntu1. The next Ubuntu change will be 1.3-2ubuntu2. And if Ubuntu is preparing a new release instead of taking it from Debian, it will be called 1.4-0ubuntu1 as to keep the Ubuntu version number below the Debian one (this allows erasing the Ubuntu version with the Debian version when it's in sync).

For the ubuntu-mobile PPA, we usually pick the "um" namespace; for example if you take claws-mail 3.3.0-1ubuntu4 from hardy/universe and change it slightly for UME to prepare a PPA upload for hardy, you could name the source 3.3.0-1ubuntu4um1. It's also acceptable to use a + to split the version in a more readable fashion, but is longer: 3.3.0-1ubuntu4+um1.

If you're building a package from scratch rather than based on something already in Ubuntu, you do not necessarily need to include "ubuntu" in the version number. The only technical effect of "ubuntu" is that the script that synchronises new versions of packages from Debian into Ubuntu will skip all packages whose version numbers contain the substring "ubuntu". This may not be needed for packages in other archives. Of course, if you're producing a package based on one from Ubuntu, you will usually want to retain the "ubuntu" part.

Avoid native versioning

Even when we have commit access to the upstream repository, it makes more sense to allow for packaging updates without incrementing the upstream version (ubuntu1, ubuntu2 etc.). There are almost no packages which are specific to Ubuntu, so try to follow an upstream versioning scheme upstream and an Ubuntu versioning scheme in Ubuntu.

Practical guidelines for the UME PPAs

• If you take version 1.2-0ubuntu2 from Ubuntu hardy for the ubuntu-mobile hardy PPA and change it for UME, rename it to 1.2-0ubuntu2+804um1.
• If you take version 1.2-0ubuntu2 from Ubuntu hardy for the ubuntu-mobile gutsy PPA and change it for UME, rename it to 1.2-0ubuntu2+710um1.
• If you take version 1.2-0ubuntu2 from Ubuntu hardy for the ubuntu-mobile gutsy PPA and *DO* *NOT* change it for UME, i.e. simple backport, rename it to 1.2-0ubuntu2~710um1; this will make dist-upgrades to hardy pick the original hardy version.
• If you take version 1.2-0ubuntu2 from Ubuntu hardy for the ubuntu-mobile gutsy PPA and also have to change it for UME, i.e. backport + changes, rename it to 1.2-0ubuntu2~710um1 too but make sure there's a version for hardy with your changes for example 1.2-0ubuntu2+804um1 (in the hardy PPA) so that a dist-upgrade picks the hardy PPA version with your changes.

More Links

• http://help.launchpad.net/PPA

• http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version