Upstream Versioning Recommendation

Upstream Versioning Recommendation (Draft)

This text tries to communicate with upstream projects about implications of different kind of software versioning schemes from downstream point of view.

While listing the schemes that cause more workload and attention in downstream, it also gives a recommendation that should work for most of the upstreams and be straight forward for packager. For each upstream project it is their own decision to choose best practice.

Document role
Note that this is only a recommendation and its role is only informal. It intends to be a short summary of package version issues in distribution level.

Motivation

Software release versions are important. They are used by many software like dpkg and rpm, but also their network counterparts like apt and yum which all use versions to determine is given version newer or older compared to another. Versions are cornerstones of automation but also play vital role for software compatibility when dependency chains grow large.

Some versioning schemes need more attention than others when packaged into distribution specific packages. If a package maintainer fails pay that attention, future upstream releases may have versions that break automatic package upgrade path meaning that with given versions, package will not get updated automatically.

When successfull, all this extra workload and attention is lost work hours and away from more productive distribution work, causes extra package builds in build system (equals to loss of computing power, storage and electricity) even may cause problems for end users. Thus all of it should be avoided if possible.

Anatomy of RPM Version

A full package file name could look as following:

<name>-[epoch:]<version>-<release>.<arch>.rpm

• name is typically upstream package name like firefox, pine.
• epoch is an integer number, typically it does not exist.
• version is upstream version as it comes.
• release is composed in Fedora project and used to distinguish builds from each other. It can also contain so called %{dist} tag denoting the distribution release.
• arch could be i386, i686, x86_64 etc.

Problematic Cases

While Packaging Guidelines describes these cases in great detail, here we outline an abstract of the issue. The main source of the problems is non-numeric symbols in version. There are three cases when these are typically used:

• pre-release versions
• post-release versions

In these cases, Packaging Guidelines describe how these string parts in version may have to be moved into package Release Tag.

Examples:

mozilla-1.4a.tar.gz          ------>    mozilla-1.4-0.1.a.f14.x86_64.rpm
alsa-lib-0.9.2beta1.tar.gz   ------>    alsa-lib-0.9.2-0.1.beta1.f14.x86_64.rpm

foo-1.1.0GA1.tar.gz          ----->     foo-1.1.0-0.2.GA1.f14.x86_64.rpm
foo-1.1.0CP1.tar.gz          ----->     foo-1.1.0-0.2.CP1.f14.x86_64.rpm

Another set of cases are SCM snapshots, but those are treated equally with every project regardless of their version scheme.

Ugly Workarounds

If a packager fails to convert an upstream version into correct package version+release combination and such build ends up into official Yum repositories, that forces packager to add an Epoch tag into package metadata:

Quote from Packaging Guidelines: Use of Epochs
The Epoch tag in RPM is to be used only as a last resort, and should be avoided whenever possible. However, it is sometimes necessary to use an Epoch to handle upstream versioning changes or to ease transition from third party repositories.

Use of Epoch is irrevocable decision for whole package lifespan and causes even more attention in future package updates.

Optimal Versioning

Projects should avoid using non-numerical versions.

Examples:

glibc-2.12.90.tar.gz               ---->     glibc-2.12.90-21.x86_64.rpm
firefox-3.6.13.tar.gz              ---->     firefox-3.6.13-1.fc14.x86_64.rpm

See Also

• NamingGuidelines#Package_Version
• NamingGuidelines#Package_Versioning
• Packaging:DistTag
• Packaging/Guidelines#Use_of_Epochs