+ include::{partialsdir}/versions.adoc[]

+ 

+ = Classic Versioning Guidelines

+ :toc:

+ 

+ This page documents the versioning scheme

+ used in Fedora 30 and earlier,

+ as well as EPEL8 and earlier.

+ The version of RPM in those releases

+ does not support the caret (`+^+`) comparison operator

+ and thus requires a more complicated scheme

+ for versioning snapshots.

+ 

+ Use of this scheme is permitted

+ in all Fedora and EPEL releases.

+ 

+ Fedora's package versioning scheme

+ encompasses both the `+Version:+`

+ and `+Release:+` tags, as well as `+Epoch:+`.

+ The overriding goal is to provide sequences of packages

+ which are treated as updates by RPM's version comparison algorithm

+ while accommodating varied and often inconsistent upstream versioning schemes.

+ 

+ == 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 https://fedoraproject.org/wiki/Package_Versioning_Examples[Package Versioning Examples].

+ 

+ == Epoch: tag

+ 

+ The `+Epoch:+` tag provides the most significant input to RPM's version comparison function.

+ If present, it MUST consist of a positive integer.

+ It SHOULD ONLY be introduced or incremented

+ when necessary to avoid ordering issues.

+ The `+Epoch:+` tag, once introduced to a package,

+ MUST NOT ever be removed or decreased in any way.

+ 

+ == 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 xref:DistTag.adoc[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.

+ * You need to apply a small fix to a release branch of Fedora

+   without updating the newer branches.

+ * 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>+`)

+ * minor release bump (`+<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 `+<extraver>+` or `+<snapinfo>+`,

+ and in most situations `+<minorbump>+` won't be used at all.

+ Simply do not include those which you don't have.

+ 

+ Note that the Dist tag is supplied by other portions of the system

+ and may in some circumstances contain additional structure,

+ including tildes.

+ As this is not under the control of the packager,

+ that structure is not covered here.

+ The packager MUST simply include `+%{?dist}+` verbatim

+ as indicated above.

+ 

+ === 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 `+<extraver>+` 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 `+<extraver>+`.

+ 

+ === 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 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.

+ 

+ === Upstream makes unsortable changes

+ 

+ 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.

+ 

+ === You need to change an old branch without rebuilding the others

+ 

+ Sometimes, you may find yourself in a situation where an older branch needs a fix,

+ but the newer branches are fine.

+ For example, if a package has a version-release of `+1.0-1%{?dist}+`

+ in F{CURRENTVER} and F{NEXTVER},

+ and only F{CURRENTVER} needs a fix.

+ Normally, you would need to bump the release in each of the branches

+ to ensure that F{CURRENTVER} < F{NEXTVER},

+ 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 `+<minorbump>+`

+ to an in integer beginning with '1'

+ and increasing by one for each minor bump you need to do.

+ Remove `+<minorbump>+` once you are able

+ to increase the package release normally

+ without introducing ordering issues.

+ 

+ == Versioning prereleases with tilde

+ 

+ If you wish to package a prerelease version

+ and are confident that you will need to package

+ only tagged releases and not any snapshots

+ until the next release,

+ you MAY make use of RPM's tilde ('`+~+`') notation.

+ To do this, split upstream's prerelease version into two components:

+ 

+ * the version that the next actual release will take (`+<nextrel>+`).

+ * the "prerelease" portion (`+<prerel>+`).

+ 

+ Then you construct `+Version:+` and `+Release:+` as follows:

+ 

+     Version: <nextrel>~<prerel>

+     Release: <pkgrel>%{?dist}[.<minorbump>]

+ 

+ with `+<pkgrel>+` and `+<minorbump>+` as detailed above.

+ 

+ Note that you MUST NOT mix the use of tilde with

+ the previously detailed scheme for versioning prerelease snapshots.

+ Once a snapshot has been packaged according to these guidelines,

+ any `+Version:+` which uses tilde will be seen by RPM as older

+ and thus will not serve as an upgrade to the existing package.

+ 

+ == 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.

+ :toc-title:

+ This document describes the simpler versioning scheme

+ supported as of Fedora 31.

+ Older releases of Fedora,

+ as well as EPEL 8 and older,

+ do not support the use of the caret (`+^+`) comparison operator

+ and this cannot use these guidelines.

+ Please see

+ xref:ClassicVersioning.adoc[the classic versioning guidelines]

+ instead.

+ 

+   Fedora needs to indicate that,

+   but needs to make sure that the ordering is correct

+   so that the Fedora package will urpoer upgrade

+   to that version when it is actually released.

+ snapshot::

+   An archive taken from upstream's source code control system

+   which is not associated with any release version.

+ 

+ are available from

+ https://fedoraproject.org/wiki/Package_Versioning_Examples[Package Versioning Examples].

+ 

+ == Release: tag

+ 

+ The `+Release:+` tag provides the least significant input

+ to RPM's version comparison function.

+ It MUST consist of a positive integer, with the

+ xref:DistTag.adoc[Dist tag] appended.

+ This integer MUST begin at 1 and MUST be incremented

+ for each change made to the package

+ that does not involve a change to the `+Version:+` tag.

+ When a change is made that does change the `+Version:+` tag,

+ the `+Release:+` tag integer MUST be reset to 1.

+ 

+ In the case that you need to make a change

+ to a pacakge in an older branch of Fedora

+ without rebuilding package for newer branches,

+ you MAY append a period

+ and a second positive integer,

+ beginning at 1.

+ This goes after the Dist tag:

+ 

+     Release: 3%{?dist}.1

+ 

+ == Version: tag

+ 

+ The `+Version:+` tag is where upstream's chosen version information is placed.

+ In must cases

+ (where you are not packaging a prerelease or a snapshot)

+ you can just use the version information from upstream

+ directly in `+Version:+`.

+ If upstream uses dashes,

+ you may need to remove them or change them

+ to either periods or underscores.

+ When you do want to package a prereleasee or snapshot,

+ or your upstream uses a very odd versioning scheme,

+ you may need to modify the version information provided by upstream

+ to make a complete `+Version:+` tag.

+ 

+ There are potentially three fields

+ which comprise the structured `+Version:+` tag:

+ 

+ * Upstream release version (`+<upstreamrel>+`)

+ * Upstream prerelease identifier (`+<upstgreamprerep>+`)

+ * Snapshot information (`+<snapinfo>+`)

+ Those items which are present are combined

+ to construct the final `+Version:+` tag

+ in the following form.

+ Square brackets are used to indicate

+ that a component which might be omitted

+ if it does not apply.

+ 

+ * `+<upstreamrel>[~<upstreamprerel>][^<snapinfo>]+`

+ 

+ A tilde (`+~+`) indicates a prerelase

+ and a caret (`+^+`) indicates a snapshot.

+ The tilde, if present, always comes before the caret.

+ These characters are special to RPM

+ and provide for special version comparisons.

+ See

+ https://fedoraproject.org/wiki/Package_Versioning_Examples[Package Versioning Examples]

+ for examples of how these work.

+ 

+ The actual values to be used for the three fields

+ in the structured `+Version:+` tag

+ are given in the sections below.

+ 

+ 

+ == Prerelease versions

+ 

+ When packaging a prerelease:

+ 

+ * `+<upstreamrel>+` contains the version

+ which upstream has decided this line of development will become

+ once it has been released.

+ * `+<upstreamrel>+` is followed by a tilde.

+ * `+<upstreamprerel>+` contains a string which upstream has chosen

+ to version the prereleases in this line of development.

+ Usually this will be something like

+ "alpha3" or "pre2"

+ and may need to be altered such that it includes

+ no invalid characters.

+ (See <<invalidchars,below>>.)

+ 

+ Note that it is possible that upstream has decided

+ on the next release version

+ but has not yet tagged a prerelease.

+ In this case you would be packaging a snapshot

+ (see below)

+ and you would simply leave `+<upstreamprerel>+` empty

+ *while still including the tilde*.

+ This ensures that everything sorts properly

+ when a prerelease is actually tagged.

+ 

+ 

+ == Snapshots

+ 

+ When packaging a snapshot, `+<snapinfo>+` must at minimum consist of

+ the date in eight digit `+YYYYMMDD+` format.

+ The packager MAY include up to 17 characters

+ of additional information

+ * `+YYYMMDD.<revision>+`

+ * `+YYYMMDD<scm><revision>+`

+ identifying the source code control upstream uses

+ (e.g. `+git+`,`+svn+`, `+hg+`)

+ or the string `+snap+`.

+ `+<revision>+` is either a short git commit hash,

+ or something else useful in identifying

+ the previse revision

+ no such revision information exists

+ If you need to take multiple snapshots per day,

+ you MAY use a data format like `+YYYYMMDD.HH+`

+ or `+YYYYMMDD.N+`

+ where `+HH+` is the hour

+ or `+N+` is an integer used as a counter.

+ You can intruduce this extra information when needed

+ and go back to using the plain date the next day.

+ In the `+Version:+` tag, `+<snapinfo>+` MUST be preceded

+ by a caret (`+^+`).

+ If you take a snapshot which comes after a prerelease,

+ the `+Version:+` tag MUST still include the prerelease information

+ as indicated above.

+ So a snapshot taken after beta1 has been relased

+ (but before beta2 or rc2 or the final release is tagged)

+ still indicates "beta1" in the `+Version:+` tag.

+ If you are packaging a prerelease snapshot

+ where upstream has chosen the next version

+ but not yet tagged any prerelease,

+ the `+Version:+` tag

+ *still includes both the tilde and the caret*,

+ as in `+1.2~^20200101.abcdef+`.

+ If upstream later releases "1.2 beta1"

+ then things will sort properly

+ if these rules are followed.

+ In the rare case that upstream makes unsortable prerelease tags,

+ there may be an alternative to intruducing `+Epoch:+`.

+ You can instead insert an integer in the `+Version: tag+`

+ before the prerelease information.

+ So from the following sequence:

+ 

+ * `+1.2 beta+`, `+1.2 gamma+`, `+1.2 delta+`

+ 

+ You can use the following versions

+ 

+ * `+1.2~beta+`, `+1.2~gamma+`, `+1.2~1.delta+`

+ 

+ In general, if it is possible to insert an integer

+ into a version sequence in such a way

+ that it doesn't imply a version not actually released by upstram,

+ then doing this is preferable to introducing `+Epoch:+`.

+ 

+ 

+ === Upstream has never chosen a version

+ 

+ When upstream has never chosen a version,

+ you MUST use `+0+` for `+<upstreamrel>+`

+ and otherwise follow the guidelines for prerelease snapshots.

+ This will give a `+Version:+` tag similar to

+ `+0~^20200101.abcdef+`.

+ Then if upstream tags a prerelease

+ or even decides to release version 0,

+ a `+Version:`+ tag chosen according to these guidelines

+ will still update existing systems properly

+ without ordering issues.

+ 

+ 

+ [#invalidchars]

+ === 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.

+ 

+ 

+ == Transitioning from previous guidelines

+ 

+ These guidelines, when followed closely,

+ should provide for proper package ordering

+ for all reasonable upstream versioning schemes.

+ However, some previous versions of these guidelines

+ prohibited the use of tilde

+ and support for using caret was only added in RPM 4.15.

+ So before applying these guidelines to an existing package,

+ it is important to ensure that the versioning

+ does not go "backwards".

+ 

+ For post-release snapshots, there should be no issues.

+ The snapshot information can be moved out of the

+ `+Release:+` tag and into the `+Version:+` tag

+ (with the `+Release:+` tag being reset to 1)

+ without issue.

+ 

+ Tagged prereleases using tilde should generally work fine as well.

+ These guidelines and the classic guideliens

+ give identical `+Version:+` tags for tagged prereleases,

+ and the classic guidelines did not permit the mixing

+ of tilde and snapshots.

+ 

+ Prerelease snapshots will generally have ordering problems,

+ because moving from, for example, a version-release pair of

+ `+1.2-0.1beta1+` or `+1.2-0.2.20200101.abcdef+`

+  to `+1.2~beta1-1" or `+1.2~^20200101.abcdef-1+`

+ would result in something RPM does not see as an upgrade.

+ In this case,

+ xref:ClassicVersioning.adoc[the classic versioning guidelines]

+ MUST continue to be followed.