openSUSE:Package versioning guidelines
In general, the version for the Version: line in .spec files should follow the upstream tarball version.
If this is not possible, please check if one of the solutions below can address your case.
Unusual characters
RPM uses the dash to separate the package name, the package version and the distro-level re-issue ("release") counter. (`rpm -qa` for example emits coreutils-9.0-1.x86_64.) The dash itself is unavailable for use within the version or release substring, as are a few other characters like the asterisk. Most software uses dots as separators and everything is fine. However, a few projects eschew all conventions. Anything that is not an alphanumeric character or a dot should be outright replaced by a dot. The tilde character is exempt from this treatment since that is for beta sorting (see below).
SCM snapshots
When creating tarballs from an SCM repository, use the nearest applicable release version, append the '+' delimiter and a short tag identifying the SCM type and an SCM-specific monotonically increasing identifier. Examples for common applications of this scheme:
Git can express a commit as an offset from a tag to yield a relatively short identifier. For example, if `git describe` outputs v3.14.1-5-g9265358, the rpm version could be set to 3.14.1+git5 or, if more disambiguation is desired, 3.14.1+git5.g9265358. You may need to use `git describe --tags` if the git repository maintainer uses only simple tags rather than annotated tags. If the maintainer provides no git tags, report that shortcoming. In the meantime, an alternative monotonically increasing identifier can be obtained by using the history root as a base (`git rev-list 9265358 | wc -l`), useful for when a project is in such an early stage that there have not been any releases yet (Version: 0~git123).
Subversion has revision numbers which can directly be used. The base version however needs to be determined in other ways. Version: 3.14.1+svn592.
For CVS, a timestamp seems the shortest unambiguous (to the developer, at least) snapshot identifier because all files have their own revision tree. Version: 3.14.1+cvs20130621.
Pre-Release packages
Pre-release versions using the same version number as the final releases need some additional care. Different developers have different ideas about how to name their preleasess; "1.8b" could indicate either 1.8 beta that comes before 1.8, or it could indicate a release actually made after 1.8. As such, package utilities (correctly so) make no effort to special-case âalphaâ, âbetaâ, âaâ, âbâ, or any other name for that matter, and usually sort by longest string such that "1.8" comes before "1.8b". A distro package maintainer is to tweak the Version: field in the .spec file in accordance with the sort order provided by our utilities. There are a number of ways to choose from, but pick one only. In the order of descending preference (= pick the first that is applicable), they are:
- Some upstreams assign their prereleases sortable numbers (that no other normal release will obtain). For example, sssd-1.8.0beta2.tar.gz is defined to be â1.7.92â. Use Version: 1.7.92.
- Use âtilde versionsâ. The spec's Version: field may contain a tilde as a special marker that sorts before anything else, including the end-of-string, that is, "1.8~" < "1.8". This feature is available starting from rpm-4.10 (and was backported into openSUSE 12.2's rpm 4.9.1). Use: Version: 1.8.0~beta2. Tildes can be used multiple times, should it really become necessary.
- If the upstream tarball doesn't contain the tilde character, you may find the following lua macro that removes tilde from the version useful:
Version: 1.8.0~beta2
%define pkg_version %{lua: print((string.gsub(rpm.expand("%{version}"), "~", "")))}
Source: https://example.com/%{name}-%{pkg_version}.tar.gz
etc.
- For the final release, choose a version string that sorts after the upstream final but before any future release. (Choices are indeed limited.) Version: 1.8.0.beta2 for the prerelease, Version: 1.8.0.0 for the final. This relies on the property that RPM sorts AâZ before 0â9. As you have noticed, rpm does not bluntly sort by ASCII value, and so, this variant may not necessarily work with non-RPM systems, should you plan to build for them too using OBS.
- For the prerelease, choose a version that sorts before the final but after any potential future releases in the series, and use it to prefix the actual version. Version: 1.7.99_1.8.0beta2 for the prerelease, Version: 1.8.0 for the final.
- Bumping the Epoch: field. Note that openSUSE discourages and does not use epochs, one reason being that zypper can actually handle downgrades (unlike yum, presumably) with `zypper dup` and `zypper in`. In fact, Epoch is considered harmful, citing the Maximum RPM book:
Do not attempt to abuse the rpm Release: tag for version information either. It is the wrong field to convey this information, and the Open Build Service will by default overwrite Release: anyway with checkin and build counters.
Post-Release packages
By and large, post releases generally pose no problem because upstreams generally version them such that they follow final releases.
If upstream is using delimiters from the permitted character set, then just reuse that for the version string. Otherwise replace them by something permitted.
- openssl-0.9.8p: Version: 0.9.8p
- suse-11-GA1: Version: 11.GA1 # GA=General Availability
Again, letter strings that only have meaning to humans (like GA here) may need to be prefixed by something like a number that helps ordering them the way upstream intended if the natural order of AâZ is not sufficient. Assuming FUBAR comes after GA, then
- suse-11-GA1: Version: 11+0.GA1
- suse-11-FUBAR1: Version: 11+1.FUBAR1
would be a workable solution. You will notice '+' was chosen here by the wiki page editor instead of '.' as a delimiter here, for reason to avoid somewhat ambiguous versions (11.0.GA1 could either be interpreted as 11.0+GA1 or 11+0.GA1).
For prereleases to postreleases, simply use the tilde mechanism as described above (âopenssl-0.9.6q~betaXâ).