From Fedora Project Wiki
(Import proper Versioning Guidelines)
(13 intermediate revisions by 2 users not shown)
Line 18: Line 18:
 
There are four cases where the version contains non-numeric characters:
 
There are four cases where the version contains non-numeric characters:
  
* Pre-release packages: Packages released as "pre-release" versions, prior to a "final" version. Example tags include "alpha", "beta", "rc", "cvs". Unfortunately, we cannot simply put these letters into the version tag, so we use the Release field for this. Details can be found here: [[#NonNumericReleaseNon-Numeric Version in Release]]  
+
* Pre-release packages: Packages released as "pre-release" versions, prior to a "final" version. Example tags include "alpha", "beta", "rc", "cvs". Details can be found here: [[#Pre-Release_PackagesPre-Release Packages]]  
  
* Post-release packages: Packages released after a "final" version. These packages contain the same numeric version as the "final" version, but have an additional non-numeric identifier. Details can be found here: [[#NonNumericReleaseNon-Numeric Version in Release]]  
+
* Post-release packages: Packages released after a "final" version. These packages contain the same numeric version as the "final" version, but have an additional non-numeric identifier. Details can be found here: [[#Post-Release PackagesPost-Release Packages]]  
  
* Snapshot packages: Packages built from cvs or subversion snapshots. These packages could be either "pre" or "post" release packages. Details can be found here: [[#NonNumericReleaseNon-Numeric Version in Release]]  
+
* Snapshot packages: Packages built from cvs or subversion snapshots. These packages could be either "pre" or "post" release packages. Details can be found here: [[#Snapshot_PackagesSnapshot Packages]]  
  
 
* JPackage derived Fedora packages: Packages which derive from JPackage RPMS follow a special policy. Details can be found here: [[Packaging/JPackagePolicy|JPackagePolicy]]  
 
* JPackage derived Fedora packages: Packages which derive from JPackage RPMS follow a special policy. Details can be found here: [[Packaging/JPackagePolicy|JPackagePolicy]]  
  
{{admon/note|Non-use of tilde "~"|rpm-4.10 and above support the Debian-style tilde character which causes a piece of the version to sort before anything else.  At the moment, using this is not permitted for these reasons:
+
==== Basic versioning rules ====
* it is not necessary when the following release tag guidelines are followed properly.
 
* it introduces another special character to achieve something which can be handled in other ways.}}
 
  
=== Release Tag ===
+
* Separators (e.g. <code>.</code>, <code>+</code>, <code>_</code>) are ignored by RPM's comparison - <code>1+0 == 1.0</code>
The release tag of packages which are not pre- or post-release or snapshots must consist of a positive integer release number and a %{?dist} tag: <code>42%{?dist}</code>.  When a minor change (spec file changed, patch added/removed) occurs, or a package is rebuilt to use newer headers or libraries, the release number is incremented. If a major change (new version of the software being packaged) occurs, the version number is changed to reflect the new software version, and the release number is reset to 1. It is important to follow these guidelines because automated tools will occasionally be used to increment releases and rebuild packages.
+
 
 +
* <code>A-Z</code> are sorted '''before''' <code>0-9</code> - <code>1+a < 1.0</code>
 +
 
 +
* Additional character makes version being higher - <code>1.1 < 1.10</code>
 +
 
 +
* Tilde (<code>~</code>) makes version being lower - <code>1.0 > 1.0~</code>, <code>1.0 > 1.0~rc1</code>
 +
 
 +
* Zero (<code>0</code>) after separator handled natively - <code>1.0 == 1.000</code>
  
==== Non-Numeric Version in Release ====
+
==== Non-Numeric Versions ====
There are three cases in which non-numeric versions occur in the Release field:
+
There are three cases in which non-numeric versions occur in the Version field:
  
 
* Snapshot packages
 
* Snapshot packages
Line 40: Line 45:
 
* Post-release packages
 
* Post-release packages
  
===== Snapshot packages =====
+
{{admon/note|Epoch usage in upgrades|If during usage of tilde or any other separators you see that it will introduce downgrade (e.g. <code>1~gitX -> 1~alpha</code>, <code>g</code> considered higher than <code>a</code>) - bump Epoch.}}
 +
 
 +
===== Snapshot Packages =====
  
 
Snapshot packages contain data about where the snapshot came from as well as
 
Snapshot packages contain data about where the snapshot came from as well as
Line 65: Line 72:
 
follow the guidelines listed in Pre-Release Packages for snapshot packages,
 
follow the guidelines listed in Pre-Release Packages for snapshot packages,
 
using the %{checkout} that you decide on above.  (For instance, in
 
using the %{checkout} that you decide on above.  (For instance, in
kismet-0-0.3.20040204svn, 20040204svn is the %{checkout})
+
kismet-0~20040204svn-3, 20040204svn is the %{checkout})
  
 
If the snapshot is a "post-release package", follow the
 
If the snapshot is a "post-release package", follow the
Line 75: Line 82:
 
kismet-1.0-1%{?dist} (this is the formal release of kismet 1.0)
 
kismet-1.0-1%{?dist} (this is the formal release of kismet 1.0)
 
kismet-1.0-2%{?dist} (this is a bugfix build to the 1.0 release)
 
kismet-1.0-2%{?dist} (this is a bugfix build to the 1.0 release)
kismet-1.0-3.20050515cvs%{?dist} (move to a post-release cvs checkout)
+
kismet-1.0+20050515cvs-1%{?dist} (move to a post-release cvs checkout, note the reset of the Release section)
kismet-1.0-4.20050515cvs%{?dist} (bugfix to the post-release cvs checkout)
+
kismet-1.0+20050515cvs-2%{?dist} (bugfix to the post-release cvs checkout)
kismet-1.0-5.20050517cvs%{?dist} (new cvs checkout, note the increment of %{X})
+
kismet-1.0+20050517cvs-1%{?dist} (new cvs checkout, note the reset of the release tag)
 
</pre>
 
</pre>
  
===== Pre-Release packages =====
+
===== Pre-Release Packages =====
 
Non-numeric versioned "pre-release" packages can be problematic so they must be treated with care.
 
Non-numeric versioned "pre-release" packages can be problematic so they must be treated with care.
These are cases where the upstream "pre-release" version has letters rather than simple numbers in their version.  Often they have tags like alpha, beta, rc, or letters like a and b denoting that it is a version before the "final" number. Unfortunately, we cannot simply put these letters into the version tag, so we'll use the Release field for this.
+
These are cases where the upstream "pre-release" version has letters rather than simple numbers in their version.  Often they have tags like alpha, beta, rc, or letters like a and b denoting that it is a version before the "final" number. We need to follow a special scheme to ensure proper ordering in the Version field.
  
Release Tag for Pre-Release Packages:
+
Version Tag for Pre-Release Packages:
<code>0.%{X}.%{alphatag}%{?dist}</code>
+
<code>%{X}~%{alphatag}</code>
  
Where <code>%{X}</code> is the release number increment, and <code>%{alphatag}</code> is the string that came from the version.
+
Where <code>%{X}</code> is the software version that the pre-release will become, and <code>%{alphatag}</code> is the string indicating the pre-release state.
In this case, the period '.' is used as the delimiter between the release number increment, and the non-numeric version string. No other extra characters may appear in the Release field. This is to prevent Release values such as "3jpp_2fc.42-spotwashere%{?dist}".
+
In this case, the tilde '~' is used as not only a separator, but also an indicator for RPM to consider it lower than a package that just has <code>%{X}</code> in the Version field.
  
===== Examples =====
+
====== Examples ======
 
{|
 
{|
 
|+ '''Example (mozilla pre-release)'''
 
|+ '''Example (mozilla pre-release)'''
Line 100: Line 107:
 
| <code>mozilla-1.4.tar.gz</code> || (this is what the 1.4 release will actually look like)
 
| <code>mozilla-1.4.tar.gz</code> || (this is what the 1.4 release will actually look like)
 
|-
 
|-
! Release Tag !! Explanation
+
! Name-Version-Release !! Explanation
 
|-
 
|-
| <code>mozilla-1.4-0.1.a%{?dist}</code> || (so, this is the acceptable Fedora <code>%{name}-%{version}-%{release}</code>)
+
| <code>mozilla-1.4~a-1%{?dist}</code> || (so, this is the acceptable Fedora <code>%{name}-%{version}-%{release}</code>)
 
|-
 
|-
 
| <code>mozilla-1.4-1%{?dist}</code> || (and this is what the 1.4 release Fedora <code>%{name}-%{version}-%{release}</code> should be)
 
| <code>mozilla-1.4-1%{?dist}</code> || (and this is what the 1.4 release Fedora <code>%{name}-%{version}-%{release}</code> should be)
Line 115: Line 122:
 
|style=white-space:nowrap| <code>alsa-lib-0.9.2beta1.tar.gz</code> || (this is a beta release of alsa-lib, version 0.9.2beta1)
 
|style=white-space:nowrap| <code>alsa-lib-0.9.2beta1.tar.gz</code> || (this is a beta release of alsa-lib, version 0.9.2beta1)
 
|-
 
|-
! Release Tag !! Explanation
+
! Name-Version-Release !! Explanation
 
|-
 
|-
| <code>alsa-lib-0.9.2-0.1.beta1%{?dist}</code> || (this is the correct Fedora <code>%{name}-%{version}-%{release}</code>)
+
| <code>alsa-lib-0.9.2~beta1-1%{?dist}</code> || (this is the correct Fedora <code>%{name}-%{version}-%{release}</code>)
 
|-
 
|-
| <code>alsa-lib-0.9.2-0.2.beta1%{?dist}</code> || (this is an incremented Fedora <code>%{name}-%{version}-%{release}</code>. Note that the first 0 is not incremented.)
+
| <code>alsa-lib-0.9.2~beta1-2%{?dist}</code> || (this is an incremented Fedora <code>%{name}-%{version}-%{release}</code>.)
 
|}
 
|}
  
Line 126: Line 133:
 
|+ '''Example (kismet pre-release svn checkout)'''
 
|+ '''Example (kismet pre-release svn checkout)'''
 
|-
 
|-
! Release Tag !! Explanation
+
! Name-Version-Release !! Explanation
 
|-
 
|-
|style=white-space:nowrap| <code>kismet-0-0.1.20040110svn%{?dist}</code> || (this is a pre-release, svn checkout of kismet)
+
|style=white-space:nowrap| <code>kismet-0~20040110svn-1%{?dist}</code> || (this is a pre-release, svn checkout of kismet)
 
|-
 
|-
| <code>kismet-0-0.2.20040110svn%{?dist}</code> || (this is a bugfix to the previous package)
+
| <code>kismet-0~20040110svn-2%{?dist}</code> || (this is a bugfix to the previous package)
 
|-
 
|-
| <code>kismet-0-0.3.20040204svn%{?dist}</code> || (this is a new svn checkout, note the increment of <code>%{X}</code>)
+
| <code>kismet-0~20040204svn-1%{?dist}</code> || (this is a new svn checkout, note the reset of the Release)
 
|-
 
|-
 
| <code>kismet-1.0-1%{?dist}</code> || (this is the formal release of kismet 1.0)
 
| <code>kismet-1.0-1%{?dist}</code> || (this is the formal release of kismet 1.0)
Line 141: Line 148:
 
|+ '''Upgrade Path Example (mozilla)'''
 
|+ '''Upgrade Path Example (mozilla)'''
 
|-
 
|-
! Release Tag !! Explanation
+
! Name-Version-Release !! Explanation
 
|-
 
|-
|style=white-space:nowrap| <code>mozilla-1.4-0.1.a%{?dist}</code> || (this is the Fedora package for 1.4a, as [[#PreReleaseExampleMozilla|above]])
+
|style=white-space:nowrap| <code>mozilla-1.4~a-1%{?dist}</code> || (this is the Fedora package for 1.4a, as [[#PreReleaseExampleMozilla|above]])
 
|-
 
|-
| <code>mozilla-1.4-0.2.a%{?dist}</code> || (this is the first patch on top of 1.4a)
+
| <code>mozilla-1.4~a-2%{?dist}</code> || (this is the first patch on top of 1.4a)
 
|-
 
|-
| <code>mozilla-1.4-0.3.a%{?dist}</code> || (this is another new patch on top of 1.4a)
+
| <code>mozilla-1.4~a-3%{?dist}</code> || (this is another new patch on top of 1.4a)
 
|-
 
|-
| <code>mozilla-1.4-0.4.b%{?dist}</code> || (this is the first build after upgrade to 1.4b)
+
| <code>mozilla-1.4~b-1%{?dist}</code> || (this is the first build after upgrade to 1.4b)
 
|-
 
|-
| <code>mozilla-1.4-0.5.b%{?dist}</code> || (this is a new patch on top of 1.4b)
+
| <code>mozilla-1.4~b-2%{?dist}</code> || (this is a new patch on top of 1.4b)
 
|-
 
|-
 
| <code>mozilla-1.4-1%{?dist}</code> || (this is after moving to 1.4 "final", and to a normal version)
 
| <code>mozilla-1.4-1%{?dist}</code> || (this is after moving to 1.4 "final", and to a normal version)
Line 162: Line 169:
 
|+ '''Upgrade Path Example (alsa-lib)'''
 
|+ '''Upgrade Path Example (alsa-lib)'''
 
|-
 
|-
! Release Tag !! Explanation
+
! Name-Version-Release !! Explanation
 
|-
 
|-
|style=white-space:nowrap| <code>alsa-lib-0.9.2-0.1.beta1%{?dist}</code> || (this is the Fedora package for 0.9.2beta1, as [[#PreReleaseExampleAlsaLib|above]])
+
|style=white-space:nowrap| <code>alsa-lib-0.9.2~beta1-1%{?dist}</code> || (this is the Fedora package for 0.9.2beta1, as [[#PreReleaseExampleAlsaLib|above]])
 
|-
 
|-
| <code>alsa-lib-0.9.2-0.2.beta1%{?dist}</code> || (this is a new patch on top of 0.9.2beta1)
+
| <code>alsa-lib-0.9.2~beta1-2%{?dist}</code> || (this is a new patch on top of 0.9.2beta1)
 
|-
 
|-
| <code>alsa-lib-0.9.2-0.3.beta2%{?dist}</code> || (this is after upgrading to 0.9.2beta2)
+
| <code>alsa-lib-0.9.2~beta2-1%{?dist}</code> || (this is after upgrading to 0.9.2beta2)
 
|-
 
|-
| <code>alsa-lib-0.9.2-0.4.beta3%{?dist}</code> || (this is after upgrading to 0.9.2beta3)
+
| <code>alsa-lib-0.9.2~beta3-1%{?dist}</code> || (this is after upgrading to 0.9.2beta3)
 
|-
 
|-
| <code>alsa-lib-0.9.2-0.5.beta3%{?dist}</code> || (this is a new patch on top of 0.9.2beta3)
+
| <code>alsa-lib-0.9.2~beta3-2%{?dist}</code> || (this is a new patch on top of 0.9.2beta3)
 
|-
 
|-
| <code>alsa-lib-0.9.2-0.6.rc1%{?dist}</code> || (this is after upgrading to 0.9.2rc1)
+
| <code>alsa-lib-0.9.2~rc1-1%{?dist}</code> || (this is after upgrading to 0.9.2rc1)
 
|-
 
|-
| <code>alsa-lib-0.9.2-0.7.rc2%{?dist}</code> || (this is after upgrading to 0.9.2rc2)
+
| <code>alsa-lib-0.9.2~rc2-1%{?dist}</code> || (this is after upgrading to 0.9.2rc2)
 
|-
 
|-
 
| <code>alsa-lib-0.9.2-1%{?dist}</code> || (this is after upgrading to 0.9.2 "final", version becomes normal)
 
| <code>alsa-lib-0.9.2-1%{?dist}</code> || (this is after upgrading to 0.9.2 "final", version becomes normal)
Line 183: Line 190:
 
|}
 
|}
  
===== Post-Release packages =====
+
===== Post-Release Packages =====
 
Like pre-release packages, non-numeric versioned "post-release" packages can be problematic and also must be treated with care. These fall under two generic categories:
 
Like pre-release packages, non-numeric versioned "post-release" packages can be problematic and also must be treated with care. These fall under two generic categories:
  
* Properly ordered simple versions. These are usually due to quick bugfix releases, such as openssl-0.9.6b  or gkrellm-2.1.7a. As new versions come out, the non-numeric tag is properly incremented (e.g. openssl-0.9.6c) or the numeric version is increased and the non-numeric tag is dropped (openssl-0.9.7). In this case, the non-numeric characters are permitted in the Version: field.
+
* Properly ordered simple versions. These are usually due to quick bugfix releases, such as openssl-0.9.6b  or gkrellm-2.1.7a. As new versions come out, the non-numeric tag is properly incremented (e.g. openssl-0.9.6c) or the numeric version is increased and the non-numeric tag is dropped (openssl-0.9.7). No special handling is required here.
* When upstream uses versions that attempt to have meaning to humans instead of being easy for a computer to order. For example, GA1, CR2, PR3. In this case, the non-numeric string can be put in the Release: field using the following syntax: <code>%{X}.%{posttag}</code>
+
* When upstream uses versions that attempt to have meaning to humans instead of being easy for a computer to order. For example, GA1, CR2, PR3. In this case, the non-numeric string can be put in the Version: field using the following syntax: <code>%{X}+%{posttag}</code>
  
In this syntax, <code>%{X}</code> is the release number increment, and <code>%{posttag}</code> is the string that came from the version. Here, the period '.' is used as the delimiter between the release number increment and the non-numeric version string. No other extra characters may appear in the Release field.
+
In this syntax, <code>%{X}</code> is the base software version, and <code>%{posttag}</code> is the string that came from the version. Here, the plus '+' is used as the delimiter between the base version number and the non-numeric version string.
  
 
Example (complicated post-release):
 
Example (complicated post-release):
 
<pre>
 
<pre>
foo-1.1.0-0.1.BETA%{?dist} (this is a prerelease, first beta)
+
foo-0:1.1.0~BETA-1%{?dist} (this is a prerelease, first beta)
foo-1.1.0-0.2.BETA1%{?dist} (this is a prerelease, second beta)
+
foo-0:1.1.0~BETA1-1%{?dist} (this is a prerelease, second beta)
foo-1.1.0-0.3.BETA2%{?dist} (this is a prerelease, third beta)
+
foo-0:1.1.0~BETA2-1%{?dist} (this is a prerelease, third beta)
foo-1.1.0-0.4.CR1%{?dist} (this is a prerelease, candidate release 1)
+
foo-0:1.1.0~CR1-1%{?dist} (this is a prerelease, candidate release 1)
foo-1.1.0-0.5.CR2%{?dist} (this is a prerelease, candidate release 2)
+
foo-0:1.1.0~CR2-1%{?dist} (this is a prerelease, candidate release 2)
foo-1.1.0-1%{?dist} (final release)
+
foo-0:1.1.0-1%{?dist} (final release)
foo-1.1.0-2.GA1%{?dist} (post release, GA1)
+
foo-0:1.1.0+GA1-1%{?dist} (post release, GA1)
foo-1.1.0-3.CP1%{?dist} (post release, CP1, after GA1)
+
foo-1:1.1.0+CP1-1%{?dist} (post release, CP1, after GA1)
foo-1.1.0-4.CP2%{?dist} (post release, CP2, after CP1)
+
foo-1:1.1.0+CP2-1%{?dist} (post release, CP2, after CP1)
foo-1.1.0-5.SP1%{?dist} (post release, SP1, after CP2)
+
foo-1:1.1.0+SP1-1%{?dist} (post release, SP1, after CP2)
foo-1.1.0-6.SP1_CP1%{?dist} (post release, SP1_CP1, after SP1)
+
foo-1:1.1.0+SP1_CP1-1%{?dist} (post release, SP1_CP1, after SP1)
 
</pre>
 
</pre>
  
Line 209: Line 216:
  
 
Also, packagers using the post-release scheme should put a comment in their spec file with a brief description of the upstream conventions for naming/versioning that are being worked around.
 
Also, packagers using the post-release scheme should put a comment in their spec file with a brief description of the upstream conventions for naming/versioning that are being worked around.
 +
 +
=== Release Tag ===
 +
The release tag of packages must consist of a positive integer release number and a %{?dist} tag: <code>42%{?dist}</code>.  When a minor change (spec file changed, patch added/removed) occurs, or a package is rebuilt to use newer headers or libraries, the release number is incremented. If a major change (new version of the software being packaged) occurs, the version number is changed to reflect the new software version, and the release number is reset to 1.  It is important to follow these guidelines because automated tools will occasionally be used to increment releases and rebuild packages.
  
 
==== The %{?dist} Tag ====
 
==== The %{?dist} Tag ====

Revision as of 15:01, 8 September 2016

Warning.png
This page is a draft only
It is still under construction and content may change. Do not rely on the information on this page.


In Fedora we want to ensure that there is always an upgrade path from Fedora release to Fedora release and from Fedora release to the packages in updates. To do that we need to make sure the packages in the newer Fedora releases have an equal or higher Epoch:Version-Release (EVR) than the ones in older releases. For example, Fedora-13 ships with foo-1.0-1.fc13 and Fedora-14 ships with foo-1.0-2.fc14. This example shows that the Fedora-14 package will properly upgrade the Fedora-13 package.

A more complex example. Fedora-13 ships with foo-1.0-1.fc13 and Fedora-14 ships with foo-1.0-2.fc14. Fedora-13 gets an updated foo package: foo-1.0.1-1.fc13. This update is EVR higher than the package Fedora-13 shipped with so that's good. However, it is also EVR higher than what Fedora-14 shipped with so we need to make a Fedora-14 update at the same time, likely: foo-1.0.1-1.fc14. making that update means that someone updating from Fedora-13 with updates enabled will get the correct package on Fedora-14 with updates enabled.

The one time where we temporarily break the upgrade path is from released Fedora to rawhide. It is allowable to temporarily have a higher EVR in a released Fedora vs rawhide in cases where we need to get a fix out to users of the Fedora releases quickly (for instance, for a security issue) but the fixed package does not currently build in rawhide (for instance, because of a change in a dependent library that requires porting effort). The changes should be checked into Fedora's SCM for rawhide although there is not yet a build and getting a rawhide build that restores the upgrade path should be a priority.

rpm's understanding of what package is newer comes from the values of the Epoch, Version, and Release tags. The next few sections explain what values to use in those tags to ensure that the EVR consistently increases.

Version Tag

The Version field in the spec is where the maintainer should put the current version of the software being packaged. If the version is non-numeric (contains tags that are not numbers), you may need to include the additional non-numeric characters in the release field.

There are four cases where the version contains non-numeric characters:

  • Pre-release packages: Packages released as "pre-release" versions, prior to a "final" version. Example tags include "alpha", "beta", "rc", "cvs". Details can be found here: Pre-Release Packages
  • Post-release packages: Packages released after a "final" version. These packages contain the same numeric version as the "final" version, but have an additional non-numeric identifier. Details can be found here: Post-Release Packages
  • Snapshot packages: Packages built from cvs or subversion snapshots. These packages could be either "pre" or "post" release packages. Details can be found here: Snapshot Packages
  • JPackage derived Fedora packages: Packages which derive from JPackage RPMS follow a special policy. Details can be found here: JPackagePolicy

Basic versioning rules

  • Separators (e.g. ., +, _) are ignored by RPM's comparison - 1+0 == 1.0
  • A-Z are sorted before 0-9 - 1+a < 1.0
  • Additional character makes version being higher - 1.1 < 1.10
  • Tilde (~) makes version being lower - 1.0 > 1.0~, 1.0 > 1.0~rc1
  • Zero (0) after separator handled natively - 1.0 == 1.000

Non-Numeric Versions

There are three cases in which non-numeric versions occur in the Version field:

  • Snapshot packages
  • Pre-release packages
  • Post-release packages
Note.png
Epoch usage in upgrades
If during usage of tilde or any other separators you see that it will introduce downgrade (e.g. 1~gitX -> 1~alpha, g considered higher than a) - bump Epoch.
Snapshot Packages

Snapshot packages contain data about where the snapshot came from as well as ordering information for rpm. The information about the snapshot will be called %{checkout} in this section.

%{checkout} consists of the date that the snapshot is made in YYYYMMDD format, a short (2-5 characters) string identifying the type of revision control system or that this is a snapshot, and optionally, up to 13 characters (ASCII) alphanumeric characters that could be useful in finding the revision in the revision control system.

For instance, if you create a snapshot from a git repository on January 2, 2011 with git hash 9e88d7e9efb1bcd5b41a408037bb7cfd47220a64, %{checkout} string could be any of the following:

20110102snap
20110102git
20110102git9e88d7e

If the snapshot package is considered a "pre-release package", follow the guidelines listed in Pre-Release Packages for snapshot packages, using the %{checkout} that you decide on above. (For instance, in kismet-0~20040204svn-3, 20040204svn is the %{checkout})

If the snapshot is a "post-release package", follow the guidelines in the Post-Release Packages section. Where the %{posttag} in that section is the %{checkout} string you decided on above.

Example (post-release cvs):

kismet-1.0-1%{?dist} (this is the formal release of kismet 1.0)
kismet-1.0-2%{?dist} (this is a bugfix build to the 1.0 release)
kismet-1.0+20050515cvs-1%{?dist} (move to a post-release cvs checkout, note the reset of the Release section)
kismet-1.0+20050515cvs-2%{?dist} (bugfix to the post-release cvs checkout)
kismet-1.0+20050517cvs-1%{?dist} (new cvs checkout, note the reset of the release tag)
Pre-Release Packages

Non-numeric versioned "pre-release" packages can be problematic so they must be treated with care. These are cases where the upstream "pre-release" version has letters rather than simple numbers in their version. Often they have tags like alpha, beta, rc, or letters like a and b denoting that it is a version before the "final" number. We need to follow a special scheme to ensure proper ordering in the Version field.

Version Tag for Pre-Release Packages: %{X}~%{alphatag}

Where %{X} is the software version that the pre-release will become, and %{alphatag} is the string indicating the pre-release state. In this case, the tilde '~' is used as not only a separator, but also an indicator for RPM to consider it lower than a package that just has %{X} in the Version field.

Examples
Example (mozilla pre-release)
Source Archive Description
mozilla-1.4a.tar.gz (this is a pre-release, version 1.4a of mozilla)
mozilla-1.4.tar.gz (this is what the 1.4 release will actually look like)
Name-Version-Release Explanation
mozilla-1.4~a-1%{?dist} (so, this is the acceptable Fedora %{name}-%{version}-%{release})
mozilla-1.4-1%{?dist} (and this is what the 1.4 release Fedora %{name}-%{version}-%{release} should be)


Example (alsa-lib pre-release)
Source Archive Description
alsa-lib-0.9.2beta1.tar.gz (this is a beta release of alsa-lib, version 0.9.2beta1)
Name-Version-Release Explanation
alsa-lib-0.9.2~beta1-1%{?dist} (this is the correct Fedora %{name}-%{version}-%{release})
alsa-lib-0.9.2~beta1-2%{?dist} (this is an incremented Fedora %{name}-%{version}-%{release}.)


Example (kismet pre-release svn checkout)
Name-Version-Release Explanation
kismet-0~20040110svn-1%{?dist} (this is a pre-release, svn checkout of kismet)
kismet-0~20040110svn-2%{?dist} (this is a bugfix to the previous package)
kismet-0~20040204svn-1%{?dist} (this is a new svn checkout, note the reset of the Release)
kismet-1.0-1%{?dist} (this is the formal release of kismet 1.0)


Upgrade Path Example (mozilla)
Name-Version-Release Explanation
mozilla-1.4~a-1%{?dist} (this is the Fedora package for 1.4a, as above)
mozilla-1.4~a-2%{?dist} (this is the first patch on top of 1.4a)
mozilla-1.4~a-3%{?dist} (this is another new patch on top of 1.4a)
mozilla-1.4~b-1%{?dist} (this is the first build after upgrade to 1.4b)
mozilla-1.4~b-2%{?dist} (this is a new patch on top of 1.4b)
mozilla-1.4-1%{?dist} (this is after moving to 1.4 "final", and to a normal version)
mozilla-1.4-2%{?dist} (this is a new patch on top of 1.4 "final")


Upgrade Path Example (alsa-lib)
Name-Version-Release Explanation
alsa-lib-0.9.2~beta1-1%{?dist} (this is the Fedora package for 0.9.2beta1, as above)
alsa-lib-0.9.2~beta1-2%{?dist} (this is a new patch on top of 0.9.2beta1)
alsa-lib-0.9.2~beta2-1%{?dist} (this is after upgrading to 0.9.2beta2)
alsa-lib-0.9.2~beta3-1%{?dist} (this is after upgrading to 0.9.2beta3)
alsa-lib-0.9.2~beta3-2%{?dist} (this is a new patch on top of 0.9.2beta3)
alsa-lib-0.9.2~rc1-1%{?dist} (this is after upgrading to 0.9.2rc1)
alsa-lib-0.9.2~rc2-1%{?dist} (this is after upgrading to 0.9.2rc2)
alsa-lib-0.9.2-1%{?dist} (this is after upgrading to 0.9.2 "final", version becomes normal)
alsa-lib-0.9.2-2%{?dist} (this is a new patch on top of 0.9.2 "final")
Post-Release Packages

Like pre-release packages, non-numeric versioned "post-release" packages can be problematic and also must be treated with care. These fall under two generic categories:

  • Properly ordered simple versions. These are usually due to quick bugfix releases, such as openssl-0.9.6b or gkrellm-2.1.7a. As new versions come out, the non-numeric tag is properly incremented (e.g. openssl-0.9.6c) or the numeric version is increased and the non-numeric tag is dropped (openssl-0.9.7). No special handling is required here.
  • When upstream uses versions that attempt to have meaning to humans instead of being easy for a computer to order. For example, GA1, CR2, PR3. In this case, the non-numeric string can be put in the Version: field using the following syntax: %{X}+%{posttag}

In this syntax, %{X} is the base software version, and %{posttag} is the string that came from the version. Here, the plus '+' is used as the delimiter between the base version number and the non-numeric version string.

Example (complicated post-release):

foo-0:1.1.0~BETA-1%{?dist} (this is a prerelease, first beta)
foo-0:1.1.0~BETA1-1%{?dist} (this is a prerelease, second beta)
foo-0:1.1.0~BETA2-1%{?dist} (this is a prerelease, third beta)
foo-0:1.1.0~CR1-1%{?dist} (this is a prerelease, candidate release 1)
foo-0:1.1.0~CR2-1%{?dist} (this is a prerelease, candidate release 2)
foo-0:1.1.0-1%{?dist} (final release)
foo-0:1.1.0+GA1-1%{?dist} (post release, GA1)
foo-1:1.1.0+CP1-1%{?dist} (post release, CP1, after GA1)
foo-1:1.1.0+CP2-1%{?dist} (post release, CP2, after CP1)
foo-1:1.1.0+SP1-1%{?dist} (post release, SP1, after CP2)
foo-1:1.1.0+SP1_CP1-1%{?dist} (post release, SP1_CP1, after SP1)

It is important to be careful with the post-release scheme, to ensure that package ordering is correct. It may be necessary to use Epoch to ensure that the current package is considered newer than the previous package. In such cases, the packager should try to convince upstream to be more reasonable with their post-release versioning.

Also, packagers using the post-release scheme should put a comment in their spec file with a brief description of the upstream conventions for naming/versioning that are being worked around.

Release Tag

The release tag of packages must consist of a positive integer release number and a %{?dist} tag: 42%{?dist}. When a minor change (spec file changed, patch added/removed) occurs, or a package is rebuilt to use newer headers or libraries, the release number is incremented. If a major change (new version of the software being packaged) occurs, the version number is changed to reflect the new software version, and the release number is reset to 1. It is important to follow these guidelines because automated tools will occasionally be used to increment releases and rebuild packages.

The %{?dist} Tag

Use of the %{?dist} tag in the Release field is mandatory. Please refer to the Packaging:DistTag documentation for the details on the appropriate way to do this.

Minor release bumps for old branches

Sometimes, you may find yourself in a situation where an older branch needs a fix, but the newer branches are fine. For example, if foo = 1.0-1%{?dist} in F20 and F21, and only F20 needs a fix. Normally, you would need to bump the release in each of the branches to ensure that F20 < F21, but that is a waste of time and energy for the newer branches which do not need to be touched.

In this case, you can add an extra digit (prefixed by a period) to the very end of the release tag in the F20 branch, instead of bumping it the usual way. Example:


Release: 1%{?dist}

Release: 1%{?dist}.1

This will make a foo-1.0-1.fc20.1 package, which is still less than the foo-1.0-1.fc21 package in the F21 branch.

As necessary, the last digit (the minor release bump) can be incremented on a per-branch basis as needed. However, this must never be used in rawhide, because it is always unnecessary there. Simply increment the appropriate portion of Release: in rawhide.


BE CAREFUL WITH THIS! You always want to make sure that packages in branches can be upgraded to packages in more recent branches. Or to put it simply, F20< FC21 < F22. There is a tool in the rpmdevtools package called rpmdev-vercmp. This tool will prompt you for two sets of Epoch, Version, and Release, then tell you which is considered newer by rpm.