[Rpm-maint] [rpm-software-management/rpm] Add a rpm-version(7) man page for the rpm versioning system (PR #3885)

[Michal Domonkos]

@dmnks requested changes on this pull request.

Seems like the trickiest parts have been nitpicked and fixed, so I'll do the easy part, which is also my favorite - grammar nitpicking. :smile: 

Kidding aside, nice work, clear and easy to read and understand. It might not seem like it but the versioning system must be one of those core parts of RPM since the whole upgrade business revolves around it. Good to have it documented now :+1: 

> @@ -0,0 +1,134 @@
+RPM-VERSION(7)
+
+# NAME
+*rpm-version* - RPM version system
+
+# SYNOPSIS
+\[_EPOCH_*:*]_VERSION_[*-*_RELEASE_]
+
+# DESCRIPTION
+A label known as _EVR_ is used to refer to software versions in RPM

How about:
"A label known as _EVR_ is used to refer to software versions in RPM, and consists of up to three _components_:"

The "one to three" is correct of course but "up to three" reads a bit more naturally, I think. The fact that at least one component is needed is kinda implicit (since an empty EVR makes no sense) :smile: 

> +
+# SYNOPSIS
+\[_EPOCH_*:*]_VERSION_[*-*_RELEASE_]
+
+# DESCRIPTION
+A label known as _EVR_ is used to refer to software versions in RPM
+consisting of one to three _components_:
+
+- _VERSION_ reflects the actual packaged software version.
+- _RELEASE_ reflects packaging revisions within that software version.
+- _EPOCH_ is an artificial override to allow working around versioning
+  anomalies.
+
+All RPM packages have a _VERSION_ and a _RELEASE_. In context of an
+_EVR_ label (such as in versioned dependencies), only the _VERSION_
+component is mandatory however.

", however"

> +Notably, the dash character (*-*) can NOT be used in _VERSION_ or _RELEASE_
+as it is the component separator.
+
+## Release
+The _RELEASE_ reflects a revision within a single software version.
+Ideally, _RELEASE_ is a simple integer that is incremented whenever changes
+are made to a package, and should be reset (to 1) whenever the software
+version changes.
+
+Technically, the format is exactly the same as for _VERSION_.
+
+## Epoch
+The _EPOCH_ is a non-negative integer, separated from the version with
+a colon (*:*). It's the most significant part of an
+_EVR_, skewing version comparison to make an older version to appear newer.
+It's sometime necessary to work around version anomalies such as software

sometimes

> +as it is the component separator.
+
+## Release
+The _RELEASE_ reflects a revision within a single software version.
+Ideally, _RELEASE_ is a simple integer that is incremented whenever changes
+are made to a package, and should be reset (to 1) whenever the software
+version changes.
+
+Technically, the format is exactly the same as for _VERSION_.
+
+## Epoch
+The _EPOCH_ is a non-negative integer, separated from the version with
+a colon (*:*). It's the most significant part of an
+_EVR_, skewing version comparison to make an older version to appear newer.
+It's sometime necessary to work around version anomalies such as software
+project changing it's versioning scheme, but also packaging errors.

such as *a* software project

> +
+Technically, the format is exactly the same as for _VERSION_.
+
+## Epoch
+The _EPOCH_ is a non-negative integer, separated from the version with
+a colon (*:*). It's the most significant part of an
+_EVR_, skewing version comparison to make an older version to appear newer.
+It's sometime necessary to work around version anomalies such as software
+project changing it's versioning scheme, but also packaging errors.
+
+The epoch should be only used as a last resort. It violates the principle
+of least surprise, and changing it requires all related versioned
+dependencies in other packages to be updated accordingly.
+
+## Comparing
+Two _EVR_'s are compared left to right, component at a time.

EVRs

> +
+*1.0~beta2*
+	Pre-release *beta2* of version *1.0*. Newer than *0.99* and *1.0~beta1*,
+	older than *1.0*.
+
+*2.0^20250611*
+	Post-release snapshot *20250611* of version *2.0*. Newer than *2.0*,
+	older than *2.0.1*.
+
+# BUGS
+Various non-obvious behaviors and dark corners exist within the version
+comparison algorithm, but are difficult to address due to high risk of
+breaking existing packages:
+
+- Non-ASCII characters are ignored and thus equal: *1.1.α* equals
+  *1.1.β* and even *1.1.ββ*. *rpmbuild*(1) rejects such EVR's but it's

EVRs

> +Numeric segments are compared numerically as integers with leading zeros
+ignored, otherwise lexicographical comparison is used.
+That is, *abc123* consists of two segments: *abc* and *123* and is equal
+to *abc0123*, *abc.123* and *abc.000123* despite difference in appearance.
+
+Numeric segments are considered newer than alphabetic segments regardless
+of the actual content. When otherwise equal, the component with more
+segments is considered newer, and similarly an _EVR_ with more compoments
+is considered newer. For example, *0.0* is newer than *0* and *1.xyz* is
+older than *1.0* but newer than *1*.
+
+The segment _separator_ characters are not compared, so they can be used
+interchangeably, and multiple consecutive separators are treated as if
+only one separator was used. Thus, *1.0* is equal to *1+0* and *1+.+0*
+
+The segment _operators_ tilde (*~*) and caret (*^*) can be

Agreed, examples are clear and thus sufficient.

> +as it is the component separator.
+
+## Release
+The _RELEASE_ reflects a revision within a single software version.
+Ideally, _RELEASE_ is a simple integer that is incremented whenever changes
+are made to a package, and should be reset (to 1) whenever the software
+version changes.
+
+Technically, the format is exactly the same as for _VERSION_.
+
+## Epoch
+The _EPOCH_ is a non-negative integer, separated from the version with
+a colon (*:*). It's the most significant part of an
+_EVR_, skewing version comparison to make an older version to appear newer.
+It's sometime necessary to work around version anomalies such as software
+project changing it's versioning scheme, but also packaging errors.

it's -> its

> +
+Technically, the format is exactly the same as for _VERSION_.
+
+## Epoch
+The _EPOCH_ is a non-negative integer, separated from the version with
+a colon (*:*). It's the most significant part of an
+_EVR_, skewing version comparison to make an older version to appear newer.
+It's sometime necessary to work around version anomalies such as software
+project changing it's versioning scheme, but also packaging errors.
+
+The epoch should be only used as a last resort. It violates the principle
+of least surprise, and changing it requires all related versioned
+dependencies in other packages to be updated accordingly.
+
+## Comparing
+Two _EVR_'s are compared left to right, component at a time.

one component at a time (?)

-- 
Reply to this email directly or view it on GitHub:
https://github.com/rpm-software-management/rpm/pull/3885#pullrequestreview-3173905338
You are receiving this because you are subscribed to this thread.

Message ID: <rpm-software-management/rpm/pull/3885/review/3173905338 at github.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rpm.org/pipermail/rpm-maint/attachments/20250901/965f4580/attachment-0001.htm>