Fedora Packaging Guidelines
In Fedora, the package versioning scheme (which encompasses both the
Version: and Release: tags, as well as Epoch:) balances two
separate goals:
Fedora’s versioning scheme must adapt to whatever scheme any upstream developer may choose for versioning their software, while at the same time preserving the two goals above.
The Epoch: tag, which provides the most significant input to RPM’s
version comparison function, SHOULD ONLY be used or incremented when
necessary to avoid ordering issues. If present, it MUST contain a
positive integer. Epoch: MUST NOT ever be decreased in any way.
The tilde (~) notation which alters the way RPM does version
comparisons MUST NOT be used.
Note that upstreams may each have their own terminology and it is in general impossible to define these terms with complete generality. For some upstreams, every commit is itself considered a version. Many upstreams never make releases, instead just letting users take whatever is in the code repository at any given time.
Examples of many possible versioning scenarios are available from Package Versioning Examples.
Most upstream versioning schemes are “simple”; they generate versions like “1.2.03.007p1”. They consists of one or more version components, separated by periods. Each component is a whole number, potentially with leading zeroes. The rightmost component can also include one or more ASCII letters, upper or lower case. The value of a component must *never* be reduced (to a value which sorts lower) without a component somewhere to the left increasing. Note that the version sequence (“1.4a”, “1.4b”, “1.4”) does not meet this criterion, as “4” sorts lower than “4b”. The sequence (“1.4”, “1.4a”, “1.4b”) is, however, simple.
This is a very common versioning scheme, and the vast majority of software projects use something which works like this.
To package release versions of software using this versioning scheme:
Version: tag. Don’t trim leading
zeroes.Release: tag starting with 1 (never 0). Append the Dist
tag. Increment the release (by 1) for each
update you make. Reset to 1 whenever you change Version:.There are several ways in which the simple scheme might not work in a particular situation:
The methods for dealing with most of these issues involves potentially
removing some information from the Version: tag while imposing
additional structure onto the Release: tag. There are potentially
three fields which comprise the structured Release: tag:
<pkgrel>)<extraver>)<snapinfo>)<minorbump>)The package release number MUST always be present while the others may or may not be depending on the situation.
Those items which are present are combined (with periods to separate
them) to construct the final Release: tag. In the usual notation
where square brackets indicate that an item is optional:
<pkgrel>[.<extraver>][.<snapinfo>]%{?dist}[.<minorbump>]The actual values to be used for those three fields are situational and are referenced in the sections below. Note that your particular situation might not result in the use of or , and in most situations won’t be used at all. Simply do not include those which you don’t have.
When upstream has never chosen a version, you MUST use Version: 0.
“0” sorts lower than any other possible value that upstream might
choose. And if upstream does choose to release “version 0” then you can
immediately move to using Release: 1%{?dist} with no ordering
issues.
It’s possible that upstream uses characters besides ASCII letters (upper and lower case), digits and periods in its version. They must be removed and potentially replaced with valid characters. Any such alterations MUST be documented in the specfile. It is not possible to cover all potential situations here, so it is left to the packager to alter the upstream versioning scheme consistently.
After altering the version to be free of invalid characters, see #Unsortable versions below if the modifications, when applied to successive releases from upstream, will not order properly.
When upstream uses a versioning scheme that does not sort properly, first see if there is any portion which can be removed from the right side of the version string such that the remainder is sortable. This is often possible if upstream uses a sequence like (“1.2pre1”, “1.2pre1”, “1.2final”). If so, use the removed portion as above, and the remainder as the package version. If this splitting leaves a leading or trailing period in either value, remove it.
If this is not possible, use Version: 0 and move the _entire_ version string into .
All snapshots MUST contain a snapshot information field () in the
Release: tag. That field must at minimum consist of the date in
eight-digit “YYYYMMDD” format. The packager MAY include up to 17
characters of additional information after the date. The following
formats are suggested:
YYYYMMDD.<revision>YYYYMMDD<scm><revision>Where <scm> is a short string identifying the source code control system
upstream uses (e.g. “git”, “svn”, “hg”) or the string “snap”. <revision> is either
a short git commit hash, a subversion revision number, or something else
useful in identifying the precise revision in upstream’s source code
control system. Obviously if CVS is used, no such revision information
exists, so it would be omitted, but otherwise it SHOULD be included.
In the Version: tag, use the version that upstream has determined
the next release will be. For the <pgkrel> field of the Release: tag, use a
number of the form “0.N” where N is an integer beginning with 1 and
increasing for each revision of the package. Prerelease versions MUST
use a Release: tag strictly less than 1, as this is the sole
indicator that a prerelease has been packaged.
For the <pkgrel> field of the Release: tag, use an integer beginning with 1
and increasing for each revision of the package. Release and
post-release versions MUST use a Release: tag greater than or equal
to 1.
It is possible that upstream simply adopts a different versioning
scheme, fails to follow an expected pattern, or even simply resets their
version to some lower value. If none of the above operations can help
with giving a version which sorts properly, or give you a version which
simply sorts lower than the packages already in Fedora, then you have
little recourse but to increment the Epoch: tag, or to begin using
it by adding Epoch: 1. At the same time, try to work with upstream
to hopefully minimize the need to involve Epoch: in the future.
Sometimes, you may find yourself in a situation where an older branch
needs a fix, but the newer branches are fine. For example, if pkg =
1.0-1%{?dist} in F{{FedoraVersionNumber|previous}} and FF{{FedoraVersionNumber|current}}, and only FF{{FedoraVersionNumber|previous}} needs a fix. Normally, you would
need to bump the release in each of the branches to ensure that F{{FedoraVersionNumber|previous}} < F{{FedoraVersionNumber|current}}
but that is a waste of time and energy for the newer branches which do
not need to be touched.
In this case, you MAY set to an in integer beginning with ‘1’ and increasing by one for each minor bump you need to do. Remove once you are able to increase the package release normally without introducing ordering issues.
A package MAY temporarily have a lower EVR in Rawhide when compared to a release branch of Fedora ONLY in the case where the package fails to build in Rawhide. This permits important updates to be pushed to existing Fedora releases regardless of the current state of Rawhide.