From Fedora Project Wiki
Line 109: Line 109:
It is important to take care when doing this, as you must always preserve package ordering between Fedora releases.
It is important to take care when doing this, as you must always preserve package ordering between Fedora releases.


== Rawhide is allowed to lag ==
== Rawhide is allowed to lag temporarily ==
 
XXX Needs work.  Might not be at the right place in this document.
 
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.
 
<code>rpm</code>'s understanding of what package is newer comes from the values of the <code>Epoch</code>, <code>Version</code>, and <code>Release</code> tags.  The next few sections explain what values to use in those tags to ensure that the EVR consistently increases.


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.


[[Category:Packaging guidelines drafts]]
[[Category:Packaging guidelines drafts]]

Revision as of 02:18, 15 November 2016

In Fedora, the package versioning scheme (which encompasses both the Version: and Release: tags, as well as Epoch:) balances two separate goals:

  • To provide information about the version of the packaged software to users. When a package version does not correspond directly to the upstream version of the software, some useful information is conveyed such as the date a snapshot was taken or whether a pre- or post-release version has been packaged.
  • To ensure proper ordering between updates to a package within a Fedora release, as well as between Fedora releases. Within a release, Fedora does not allow package versions to go backwards, so the versioning scheme must produce successive versions which increase monotonically, even if the upstream versions don't have this property when compared using RPM's version comparison function. The versioning scheme also ensures that for a package built at the same time for two different Fedora releases, the version in the newer release sorts higher than the version in the older release.

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.

Note that the tilde (~) notation which alters the way RPM does version comparisons MUST NOT be used.

Some definitions

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.

release version
A version of the software which upstream has decided to release. The act of releasing the software can be as simple as adding a git tag. This includes so-called "point releases" or "patchlevels" which some upstreams make, since those are actually assigned versions and released.
snapshot
An archive taken from upstream's source code control system which is not associated with any release version.
prerelease version
Before a release happens, many upstreams will decide which version that will release will have, and then produce "alphas", "betas", "release candidates", or the like which carry that new version but indicate that the release of that version has not yet been made. These we call prerelease versions. Any snapshots made while upstream is preparing for their release are also considered prerelease versions.
postrelease version
Any version which happens after a particular release is technically "post-release", but before upstream begins making prereleases for the next version, any snapshot is considered a postrelease version.
non-sorting version sequence
A sequence of version strings which is not ordered in the same way that RPM's version comparison function would order it. RPM has a somewhat complicated version comparison function which it will use to determine if a package is "newer". If upstream's idea of what constitutes a "newer" version differs from RPM's implementation then simply using upstream's versions directly will result in updates which don't actually update any packages.

Examples

Examples of many possible versioning scenarios are available from User:Tibbs/VersioningCleanupExamples.

Simple versioning

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:

  • Use the upstream verbatim in the Version: tag. Don't trim leading zeroes.
  • Use a 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:.

More complex versioning

There are several ways in which the simple scheme might not work in a particular situation:

  • Upstream has never chosen a version; only snapshots are available for packaging.
  • Upstream simply doesn't use a version scheme which orders properly under RPM's version comparison operation.
  • You wish to package a prerelease version (snapshot or otherwise).
  • You wish to package a postrelease snapshot.
  • Upstream was thought to be following one scheme but then changed in a way that can't be sorted.
  • More than one of the above may apply (lucky you). Follow all of the relevant recommendations below together.

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:

  • package release number (<pkgrel>)
  • extra version information (<extraver>)
  • snapshot information (<snapinfo>)

The package release number MUST always be present while the others may or may not be depending on the situation. Those that are present are joined together, with periods as separators. To that, the Dist tag MUST be appended to make the final Release: tag.

The actual values to be used for those three fields are situational and are referenced in the sections below.

Upstream has never chosen a version

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.

Upstream uses invalid characters in the version

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.

Unsortable versions

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 "extra version information" above, and the remainder as the package version. If this splitting left a leading or trailing periods from either value, remove them.

If this is not possible, use Version: 0 and move the _entire_ version string into "extra version information".

Snapshots

All snapshots MUST contain a snapshot information field (<snapinfo>) 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.

Prerelease versions

In the Version: tag, use the version that upstream has determined the next release will be. For the <pkgrel> 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.

Release and post-release versions

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.

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 pkg = 1.0-1%{?dist} in F38 and F39, and only F38 needs a fix. Normally, you would need to bump the release in each of the branches to ensure that F38 < F39, 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 an extra digit (prefixed by a period) to the very end of the Release: tag in the F38 branch, instead of bumping it the usual way.

For example, you could go from Release: 1%{?dist} to Release: 1%{?dist}.1. This will make a pkg-1.0-1.fc38.1 package, which is still less than the pkg-1.0-1.fc39 package in the F39 branch.

It is important to take care when doing this, as you must always preserve package ordering between Fedora releases.

Rawhide is allowed to lag temporarily

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.