#908 Add caret-based Versioning guidelines page
Opened a year ago by tibbs. Modified a month ago
tibbs/packaging-committee caret_versioning  into  master

@@ -0,0 +1,321 @@ 

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

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

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

    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

typo

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

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

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

Those examples are now outdated. My suggestion would be to import this page into the new docs repo too, and update it at the same time.

tibbs commented a year ago

That is unrelated to this change. I mentioned the need to work on these examples in the open ticket for this issue.
The page is in the wiki to enable the community to provide examples, but again that's completely unrelated to this change.

+ 

  

  == Epoch: tag

  

@@ -66,182 +77,154 @@ 

  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.

+ == Release: tag

== Release: tag

Why describe Release tag before Version tag? I think the order should be switched.

tibbs commented a year ago

Because that puts the two shortest sections at the front, so users who want to know what goes in the release field don't have to skip the description of the Version: field.

+ 

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

This integer MUST begin at 1 and MUST be incremented for each change made to the package

That's probably not related directly to this change, but: maybe this should be relaxed to say "MUST be incremented whenever the package is rebuilt in koji" (or something to that effect). People generally don't follow this guideline as written.

tibbs commented a year ago

Unrelated to this change. Neverless, the guideline is correct. Change version, reset release. It's pretty simple, and I do think most people follow it. You wouldn't change Version and leave Release: at 27, only setting it back to one the moment you want to build.

+ 

+ In the case that you need to make a change

+ to a pacakge in an older branch of Fedora

typo: pacakge

+ without rebuilding package for newer branches,

without rebuilding package for newer branches,

... rebuilding the package

+ 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

typo: must → most

+ (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,

typo: prerelasee

... or a 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>+`)

  

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

+ 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 date in eight digit +YYYYMMDD+ format.

Is this really necessary? Including the date is additional work that doesn't really bring that much benefit for many cases (*).
The alternative scheme where a number is included ^1.git01ABCDEF, ^2.git01ABCDAA, etc, should also be allowed
by guidelines.

(*) For example, systemd "upstream" is a snapshot of a branch with backported patches (as in https://github.com/systemd/systemd-stable/commits/v242-stable), there is no meaningful "date", because the time when the patch was written is non-monotonous, so cannot be used here, and the time when the patch was backported is not particularly interesting, and the time when the snapshot was packaged doesn't say anything about the contents.

tibbs commented a year ago

This is unrelated to the change in question. Please bring it up separately.

+ The packager MAY include up to 17 characters

+ of additional information

  after the date.

  The following formats are suggested:

  

- * `+YYYYMMDD.<revision>+`

- * `+YYYYMMDD<scm><revision>+`

+ * `+YYYMMDD.<revision>+`

+ * `+YYYMMDD<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,

+ identifying the source code control 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

+ or something else useful in identifying

+ the previse revision

typo: previse

  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.

Maybe drop the part about CVS? It'll only confuse anyone below 30.

tibbs commented a year ago

Unrelated to this change. Besides, it's 100% valid, isn't it? Feel free to open a separate ticket about it if you like.

  

- === 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, `+<snapinfo>+` 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 `+<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

  

@@ -257,49 +240,99 @@ 

  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.

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

+ 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

  

This is an initial pass at converting the last draft of the tilde+caret versioning scheme I had in the wiki to an actual guideline page.

Unfortunately because the RPM support for the new scheme is rawhide-only, we will have to keep both pages around for potentially quite some time. Also note that the examples page in the wiki will need even more work (as it was never finished and then never updated after we started allowing tildes). No idea when I might be able to get to that.

Finally, I haven't put in sufficient thought into converting from the old guidelines to the new. There is a section on it but I'm not yet completely sure that it's accurate.

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

Those examples are now outdated. My suggestion would be to import this page into the new docs repo too, and update it at the same time.

This integer MUST begin at 1 and MUST be incremented for each change made to the package

That's probably not related directly to this change, but: maybe this should be relaxed to say "MUST be incremented whenever the package is rebuilt in koji" (or something to that effect). People generally don't follow this guideline as written.

without rebuilding package for newer branches,

... rebuilding the package

Maybe drop the part about CVS? It'll only confuse anyone below 30.

the date in eight digit +YYYYMMDD+ format.

Is this really necessary? Including the date is additional work that doesn't really bring that much benefit for many cases (*).
The alternative scheme where a number is included ^1.git01ABCDEF, ^2.git01ABCDAA, etc, should also be allowed
by guidelines.

(*) For example, systemd "upstream" is a snapshot of a branch with backported patches (as in https://github.com/systemd/systemd-stable/commits/v242-stable), there is no meaningful "date", because the time when the patch was written is non-monotonous, so cannot be used here, and the time when the patch was backported is not particularly interesting, and the time when the snapshot was packaged doesn't say anything about the contents.

== Release: tag

Why describe Release tag before Version tag? I think the order should be switched.

@tibbs In order to get the ball rolling, I've requested the carat version modifier to be backported to RHEL 8.

I figure if I put the request in now, we can see it land in EL8 around the same time that Fedora 31 does. :wink:

That is unrelated to this change. I mentioned the need to work on these examples in the open ticket for this issue.
The page is in the wiki to enable the community to provide examples, but again that's completely unrelated to this change.

Because that puts the two shortest sections at the front, so users who want to know what goes in the release field don't have to skip the description of the Version: field.

Unrelated to this change. Neverless, the guideline is correct. Change version, reset release. It's pretty simple, and I do think most people follow it. You wouldn't change Version and leave Release: at 27, only setting it back to one the moment you want to build.

This is unrelated to the change in question. Please bring it up separately.

Unrelated to this change. Besides, it's 100% valid, isn't it? Feel free to open a separate ticket about it if you like.

Because that puts the two shortest sections at the front, so users who want to know what goes in the release field don't have to skip the description of the Version: field.

That's not a good idea. The page is divided into sections so that people can jump to the right spot if they want. The text itself should be ordered logically, not by section size.

Unrelated to this change. Neverless, the guideline is correct. Change version, reset release. It's pretty simple, and I do think most people follow it. You wouldn't change Version and leave Release: at 27, only setting it back to one the moment you want to build.

No. As stated, every commit in dist-git would need a bumped release entry.

Re the other comments: since the text is being completely rewritten anyway, maybe it is easiest to trim and remove outdated parts. I know that strictly speaking those items could be done separately, but I don't think it does either me or the packaging committee any favours if I now open 10 tickets about modification to the same few paragraphs of text.

What's the status here? Is this PR still pursued?