Versioning Guidelines Appendix

Here are some additional versioning-related guidelines, moved here in order to keep the main page manageable.

Legacy complex versioning

The guidelines in this section are deprecated and should not be used. They exist as a historical reference for packages that don’t follow the current guidelines yet.

In this method, %autorelease is not used, and the Release: field must be managed manually.

This method for dealing with most pre- and post-release versions and unsortable versions involves potentially removing some information from the Version: tag while imposing additional structure onto the Release: tag. There are potentially four 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.

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.

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

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.

Rebuilds in older branches using <minorbump>

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

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

Want to help? Learn how to contribute to Fedora Docs ›