Versioning Guidelines

==== Simple versioning

[%header]
|===
|Upstream version | Version tag | Explanation

|1.0     |1.0         | The first release.

|1.1     |1.1         | An upstream update.

|1.2.1   |1.2.1       | Another upstream update. Extra levels of versioning are OK…

|1.3     |1.3         | …they can come and go without problems.
|===

In this case the full N-V-R could be e.g. `pkg-1.2.1-1.fc{CURRENTVER}` (immediately after an update) or `pkg-1.2.1-5.fc{CURRENTVER}` (after downstream rebuilds with the same upstream version).

[%header]
|===
|Upstream version | Version tag | Explanation

| 5.2    | 5.2        | Upstream release.

| 5.2a   | 5.2a       | Upstream introduced a letter to indicate a patch release. You trust upstream to use letters in alphabetical order, so it's OK to use the version as is.

| 5.2b   | 5.2b       | Another patch release after 5.2 — this is not a beta.

| 5.2b.1 | 5.2b.1     | Even this is OK as long as the sequence increases.

| 5.3    | 5.3        | Another upstream release.
|===

In this case the full N-V-R could be e.g. `pkg-5.2b.1-1.fc{CURRENTVER}`.

==== Complex versioning with a reasonable upstream

[%header]
|===
|Upstream version | Version tag | Notes

| 1.0.0-rc1 | `+1.0.0~rc1+` | first prerelease

| 1.0.0-rc2 | `+1.0.0~rc2+` | second prerelease

| 1.0.0     | `+1.0.0+`     | release

| 1.0.1     | `+1.0.1+`     | bugfix release

| 1.0.1-security1 | `+pkg-1.0.1.security1+` | security bufix release
|===

In this case the full N-V-R could be e.g. `pkg-1.0.0~rc2-42.fc{CURRENTVER}` (if many rebuilds were done).

==== Complex versioning with non-sorting upstream post-release versions

[%header]
|===
|Upstream version | Version tag | Notes

| 1.1.0~BETA      | `+1.1.0~BETA+` | this is a prerelease, first beta

| 1.1.0~BETA1     | `+1.1.0~BETA1+` | this is a prerelease, second beta

| 1.1.0~BETA2     | `+1.1.0~BETA2+` | this is a prerelease, third beta

| 1.1.0~CR1       | `+1.1.0~CR1+` | this is a prerelease, candidate release 1

| 1.1.0~CR2       | `+1.1.0~CR2+` | this is a prerelease, candidate release 2

| 1.1.0-1%        | `+1.1.0+` | final release

| 1.1.0-GA1       | `+1.1.0.20201001.GA1+` | post release, GA1

| 1.1.0-CP1       | `+1.1.0.20201011.CP1+` | post release, CP1, after GA1, does not sort properly

| 1.1.0-CP2       | `+1.1.0.20201101.CP2+` | post release, CP2, after CP1

| 1.1.0-SP1       | `+1.1.0.20210101.SP1+` | post release, SP1, after CP2

| 1.1.0-SP1-CP1   | `+1.1.0.20210105.SP1_CP1+` | post release, SP1_CP1, after SP1
|===

In this case the full N-V-R could be e.g. `pkg-1.1.0.20210105.SP1_CP1-1.fc{CURRENTVER}`.

==== Complex versioning with a pre- and post-release snapshots

[%header]
|===
|Upstream version | Version | Notes

| 1.0.0-rc1            | `+1.0.0~rc1+` | First prerelease

| 1.0.0-rc2            | `+1.0.0~rc2+` | Second prerelease

| git commit `f00fabd` | `+1.0.0~rc2^20210101gf00fabd+` | Post-prerelease snapshot

| 1.0.0                | `+1.0.0+`     | A release

| 1.0.1                | `+1.0.1+`     | A bugfix release

| git commit `bbbccc0` | `+1.0.1^20210203gbbbccc0+` or `+pkg-1.0.1^1.gbbbccc0+` | A snapshot

| 1.0.1-security1      | `+1.0.1.security1+` | A security bufix release. From past history we know that the bugfix releases will have sortable versions. If not, we could use '`+<date>.security1+`' instead.

| git commit `abc0202` | `+1.0.1.security1^20210301gabc0202+` or `+pkg-1.0.1.security1^1.gabc0202+` | Another snapshot
|===

In this case the full N-V-R could be e.g. `pkg-1.0.1.security1^20210301gabc0202-1.fc{CURRENTVER}`.

[#traditional-versioning]
== Traditional versioning with part of the upstream version information in the Release field

The method described in this section is deprecated, but **may** be used. As mentioned in the xref:_handling_non_sorting_versions_with_tilde_dot_and_caret[Handling non-sorting versions with tilde, dot, and caret] section above, this method is recommended for packages with complex versioning when supporting RHEL7 and other systems with old rpm versions.

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.

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

=== 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 F{CURRENTVER} that still compares lower than the one in F{NEXTVER}. 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 https://fedoraproject.org/wiki/Package_Versioning_Examples[Package Versioning Examples].


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