From 8e65c11c7df7ab5f8cd790f577027ba726db7f66 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Jun 24 2019 17:06:43 +0000 Subject: [PATCH 1/4] Make a copy of the classic versioning guidelines. --- diff --git a/guidelines/modules/ROOT/pages/ClassicVersioning.adoc b/guidelines/modules/ROOT/pages/ClassicVersioning.adoc new file mode 100644 index 0000000..af15c95 --- /dev/null +++ b/guidelines/modules/ROOT/pages/ClassicVersioning.adoc @@ -0,0 +1,310 @@ +include::{partialsdir}/versions.adoc[] + += Versioning Guidelines +:toc: + +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 (`++`) +* extra version information (`++`) +* snapshot information (`++`) +* minor release bump (`++`) + +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: + + [.][.]%{?dist}[.] + +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 `++` or `++`, +and in most situations `++` 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 <> 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 `++` 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 `++`. + +=== Snapshots + +All snapshots MUST contain a snapshot information field +(`+:+`) 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.+` +* `+YYYYMMDD+` + +Where `++` is a short string +identifying the source code control system upstream uses +(e.g. "git", "svn", "hg") +or the string "snap". +`++` 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 `++` 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 `++` +to an in integer beginning with '1' +and increasing by one for each minor bump you need to do. +Remove `++` 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 (`++`). +* the "prerelease" portion (`++`). + +Then you construct `+Version:+` and `+Release:+` as follows: + + Version: ~ + Release: %{?dist}[.] + +with `++` and `++` 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. From 060c94e9a9712d12370f8cf36f008f394359ff58 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Jun 24 2019 17:07:18 +0000 Subject: [PATCH 2/4] Explain the classic versioning guidelines. Add an explanatory note indicating where the classic versioning scheme is used. --- diff --git a/guidelines/modules/ROOT/pages/ClassicVersioning.adoc b/guidelines/modules/ROOT/pages/ClassicVersioning.adoc index af15c95..acaf778 100644 --- a/guidelines/modules/ROOT/pages/ClassicVersioning.adoc +++ b/guidelines/modules/ROOT/pages/ClassicVersioning.adoc @@ -1,8 +1,19 @@ include::{partialsdir}/versions.adoc[] -= Versioning Guidelines += 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:+`. From a28855a282c5307520de1ea67a3eee47f4c2a3ee Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Jun 24 2019 18:52:03 +0000 Subject: [PATCH 3/4] Initial import of the caret guidelines. This is a first pass at converting the combined tilde-caret guidelines over from the old wiki page. --- diff --git a/guidelines/modules/ROOT/pages/Versioning.adoc b/guidelines/modules/ROOT/pages/Versioning.adoc index af15c95..8cd34c7 100644 --- a/guidelines/modules/ROOT/pages/Versioning.adoc +++ b/guidelines/modules/ROOT/pages/Versioning.adoc @@ -1,8 +1,19 @@ include::{partialsdir}/versions.adoc[] = Versioning Guidelines +:toc-title: :toc: +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's package versioning scheme encompasses both the `+Version:+` and `+Release:+` tags, as well as `+Epoch:+`. @@ -24,10 +35,6 @@ release version:: 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, @@ -35,13 +42,14 @@ prerelease version:: 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. + 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. -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. +snapshot:: + An archive taken from upstream's source code control system + which is not associated with any release version. non-sorting version sequence:: A sequence of version strings which is not ordered @@ -52,10 +60,13 @@ non-sorting version sequence:: 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]. +are available from +https://fedoraproject.org/wiki/Package_Versioning_Examples[Package Versioning Examples]. + == Epoch: tag @@ -66,182 +77,156 @@ 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 (`++`) -* extra version information (`++`) -* snapshot information (`++`) -* minor release bump (`++`) - -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: - - [.][.]%{?dist}[.] - -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 `++` or `++`, -and in most situations `++` 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 <> below -if the modifications, -when applied to successive releases from upstream, -will not order properly. +== 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 (`++`) +* Upstream prerelease identifier (`++`) +* Snapshot information (`++`) -=== 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 `++` 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 `++`. - -=== Snapshots - -All snapshots MUST contain a snapshot information field -(`+:+`) 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 +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. + +* `+[~][^]+` + +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: + +* `++` contains the version +which upstream has decided this line of development will become +once it has been released. + +* `++` is followed by a tilde. + +* `++` 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 below XXXX xref.) +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 `++` empty +*while still including the tilde*. +This ensures that everything sorts properly +when a prerelease is actually tagged. + + +== Snapshots + +When packaging a snapshot, `++` 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.+` -* `+YYYYMMDD+` +* `+YYYMMDD.+` +* `+YYYMMDD+` Where `++` is a short string -identifying the source code control system upstream uses -(e.g. "git", "svn", "hg") -or the string "snap". -`++` is either -a short git commit hash, +identifying the source code control upstream uses +(e.g. `+git+`,`+svn+`, `+hg+`) +or the string `+snap+`. +`++` is either a short git commit hash, a subversion revision number, -or something else useful in identifying the precise revision +or something else useful in identifying +the previse revision in upstream's source code control system. Obviously if CVS is used, -no such revision information exists, +no such revision information exists so it would be omitted, but otherwise it SHOULD be included. -=== Prerelease versions +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, -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. +In the `+Version:+` tag, `++` MUST be preceded +by a caret (`+^+`). -=== Release and post-release versions +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. -For the `++` 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 @@ -257,49 +242,98 @@ 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 `++` -to an in integer beginning with '1' -and increasing by one for each minor bump you need to do. -Remove `++` 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 (`++`). -* the "prerelease" portion (`++`). - -Then you construct `+Version:+` and `+Release:+` as follows: - - Version: ~ - Release: %{?dist}[.] - -with `++` and `++` 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. +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 `++` +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. + + +=== 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 <> 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. +These guidelines can be used once upstream has made an actual release. + +The case where upstream has never made a release is similar, +as `+0~anything+` is older than 0. +In this case, you can simply omit the tilde +and still indicate the snapshot using the caret. +The end result should sort acceptably +as long as upsteam does not release version "0". +If for some reason they do, +you would need to introduce `+Epoch:+`. + == Rawhide is allowed to lag temporarily From 6eff3a64f1f5d89f7699ebf3fccff886877673c5 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Jun 24 2019 18:58:38 +0000 Subject: [PATCH 4/4] Add proper interpage link. --- diff --git a/guidelines/modules/ROOT/pages/Versioning.adoc b/guidelines/modules/ROOT/pages/Versioning.adoc index 8cd34c7..78c6612 100644 --- a/guidelines/modules/ROOT/pages/Versioning.adoc +++ b/guidelines/modules/ROOT/pages/Versioning.adoc @@ -152,17 +152,15 @@ When packaging a prerelease: * `++` contains the version which upstream has decided this line of development will become once it has been released. - * `++` is followed by a tilde. - * `++` 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 below XXXX xref.) +(See <>.) + Note that it is possible that upstream has decided on the next release version but has not yet tagged a prerelease. @@ -274,6 +272,7 @@ 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