Versioning Guidelines

Some upstreams will release "post" or "patch" versions after a regular version but before the next regular version. These can usually be handled with simple versioning with some slight adjustments. Any invalid characters MUST be replaced or removed. A packager MAY replace the valid separator characters underscore (_) and plus (+) with periods.

For example, with upstream releases 0.5.0, 0.5.0-post1, and 0.5.1, the "post-release" version should use 0.5.0.post1 in the Version tag. Note that 0.5.0.post1 sorts lower than both 0.5.1 and 0.5.0.1.

A tilde (~) is used before a version component which must sort earlier than any non-tilde component. It is used for any pre-release versions which wouldn’t otherwise sort appropriately. It is also used for pre-release snapshots, which is covered in the next section.

For example, with upstream releases 0.4.0, 0.4.1, 0.5.0-rc1, 0.5.0-rc2, 0.5.0, the two "release candidates" should use 0.5.0~rc1 and 0.5.0~rc2 in the Version tag.

A package using a snapshot MUST use the following format for the Version tag.

For example, if you want to package a snapshot from commit a1b2c3d that was made after version 0.4.1, the Version tag would be 0.4.1^1.a1b2c3d. Note that 0.4.1^<something> sorts higher than 0.4.1, but lower than both 0.4.2 and 0.4.1.<anything>.

Similarly, if you want to package a snapshot from commit d3c2b1a that is leading up to version 0.4.2, the Version tag would be 0.4.2~1.d3c2b1a. Note that 0.4.2~<something> sorts lower than 0.4.2, but higher than both 0.4.1 and 0.4.1.<anything>.

You can also package a snapshot following a pre-release version. If the upstream makes a pre-release version 0.5.0-rc1, but you want to package a snapshot from commit a3b2c1d that occured afterwards (but still before the 0.5.0 version), the Version tag would be 0.5.0~rc1^1.a3b2c1d.

When upstream has never chosen a version, you MUST use a base version of 0, followed by pre-release snapshot notation.

Version: 0. “0” sorts lower than any other possible value that upstream might choose. If upstream does choose to release "version 0", then just set Release: higher than the previous value. (When %autorelease is used, this happens automatically.)

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 simply inserting a tilde or caret is enough to make the string sortable.

For example, if upstream uses a sequence like 1.2pre1, 1.2pre2, 1.2final, then 1.2~pre1, 1.2~pre2, 1.2_final could be used as Version. The underscore (‘_’) is a visual separator that does not influence sort order, and is used here because "final" does not form a separate version component.

If this is not possible, use something similar to the snapshot version information field described above, with the upstream version moved to the second part of the snapshot information field: <date>.<version>.

For example, if upstream releases versions I, II, …, VIII, IX use 20200101.I, 20200201.II, …, 20200801.III, 20200901.IX in the Version tag.

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

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

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:

Where <scm> is a short string identifying the source code management 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 management 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 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. Pre-release versions MUST use a Release: tag strictly less than 1, as this is the sole indicator that a pre-release 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.

In the situation described in [Only an old branch needs a change], you MAY adjust the Release by appending a number after the dist tag, creating a E-V-R for F38 that still compares lower than the one in F39. Set <minorbump> to an in integer beginning with '1' and increase it 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.

Examples of many possible versioning scenarios of traditional versioning are available from Package Versioning Examples.