Thank you for your contribution. Unfortunately your PR did not build for some reason. Does it build locally for you?
If it does you can ignore the message.

What do you mean "does not build"? asciidoctor guidelines/modules/ROOT/pages/Versioning.adoc does not complain.

Some version examples "in the wild":

 po-debconf                     1.0.21-6.nmu1.fc35                                        
pocketsphinx                   1:5-0.6.prealpha.fc35                                     
postgres-decoderbufs           1.4.0-2.Final.fc35                                        
pxz                            4.999.9-21.beta.20200421git.fc34                          
python-contextlib2             0.6.0.post1-1.fc35                                        
python-cypari2                 2.1.2-0.3.b1.fc34                                         
python-d2to1                   0.2.12-19.post1.fc34                                      
python-ffc                     2019.1.0.post0-5.fc34                                     
python-pdir2                   0.3.1.post2-10.fc34                                       
python-publicsuffix2           2.20191221-3.fc34                                         
python-pygments-markdown-lexer 0.1.0.dev39-20.fc34                                       
qt4-theme-quarticurve          0.0-0.36.beta8.fc34                                       
qt5-qtwebkit                   5.212.0-0.59.alpha4.fc35                                  
rarpd                          ss981107-58.fc34                                          
rubygem-net-irc                0.0.9-18.D20121021git4cf339fa69.fc34                      
rust-ruma-signatures           0.6.0~alpha.1-2.fc34                                      
scalpel                        2.1-0.rc1.2.47815c2.fc34.12                               
sphinxbase                     1:5-0.9.prealpha.fc34                                     
xorg-x11-drv-armada            0.0.0-6.unstable.20180829git78e7116a5.fc34                
joda-time                      2.9.9-9.tzdata2017b.fc33
hfsplus-tools.src              540.1.linux3-23.fc34
icedtea-web.src                2.0.0-pre.0.3.alpha16.patched1.1.fc35
libmp4v2.src                   2.1.0-0.23.trunkREV507.fc34
wyhash.src                     final1-1.20210311gitfinal.fc35

I didn't look at all packages, but it really seems that such packages with non-numeric versions a tiny minority.

A couple of quibbles:

• I'd like to see the structure of snapshot versioning to be <scm>.<commitdate/snapdate>.<shorthash>. This makes the sorting easier to reason (since numbers are higher than letters in sorting). This also aligns with how openSUSE and Debian do this.
• It'd probably be a good idea to have note that falling back to + where ^ is not available is an option (RHEL 7). Combined with the previous suggestion, it makes the post-release sorting consistent.

I'm not a fan of the double carets. I understand the use case for when it would be necessary, but it's a quite rare edge case. It also doesn't entirely solve the problem, because upstream projects could come up with other post-release labels that don't sort correctly. My suggestion would be that post-release versions must always be converted to revision snapshot notation to ensure proper sorting, i.e. ignore the label and package the revision the label references.

The same problem of incorrectly sorting labels exists with pre-release versions (is pre1 before or after beta1?). I suggest that we allow alpha*, beta*, and rc* pre-release versions (which sort correctly), and require any other pre-release labels to be converted to revision snapshot notation.

Thank you for the reviews.

I force-pushed the branch with some minor fixups squashed into the existing commits, but actual "meaningful" changes done in two new commits, to make re-review easier.

I'm not a fan of the double carets. I understand the use case for when it would be necessary, but it's a quite rare edge case. It also doesn't entirely solve the problem, because upstream projects could come up with other post-release labels that don't sort correctly. My suggestion would be that post-release versions must always be converted to revision snapshot notation to ensure proper sorting, i.e. ignore the label and package the revision the label references.

The same problem of incorrectly sorting labels exists with pre-release versions (is pre1 before or after beta1?). I suggest that we allow alpha*, beta*, and rc* pre-release versions (which sort correctly), and require any other pre-release labels to be converted to revision snapshot notation.

I reworked this part. I realized that everything becomes simple if carets are only used for snapshots, and post-releases simply use a dot as the separator. Apart from some edge cases, a bugfix post-release is just a release.

A couple of quibbles:

• I'd like to see the structure of snapshot versioning to be <scm>.<commitdate/snapdate>.<shorthash>. This makes the sorting easier to reason (since numbers are higher than letters in sorting). This also aligns with how openSUSE and Debian do this.

I thought about this when writing the text, because I saw that quite a few packages do this. But I don't think it is a good idea, because now we rely on <scm> for the sort order. When <date> is used as the first part, we get sortable versions in all cases. If upstream makes a bugfix release, we can label it as <date>.bugfix1. If upstream converts from mercurial to git, we can label it as <date>.<newscm><shorthash>. I agree that putting <scm> first is more readable, but it just seems to fragile to recommend.

• It'd probably be a good idea to have note that falling back to + where ^ is not available is an option (RHEL 7). Combined with the previous suggestion, it makes the post-release sorting consistent.

Hmm, that would work , but seems easy to break:

$ rpmdev-vercmp 0.5.0^2020 0.5.0.01
0.5.0^2020 < 0.5.0.01
$ rpmdev-vercmp 0.5.0+2020 0.5.0.01
0.5.0+2020 > 0.5.0.01

If think that if caret is not available, the only realistic option is to fall back "traditional versioning". It's too easy to get wrong otherwise.

Hmm, that would work , but seems easy to break:

The reason for that is because you have the number as the prefix. Switching to a word as a prefix fixes this:

$ rpmdev-vercmp 0.5.0^snap2020 0.5.0.01
0.5.0^snap2020 < 0.5.0.01
$ rpmdev-vercmp 0.5.0+snap2020 0.5.0.01
0.5.0+snap2020 < 0.5.0.01

Perhaps we should just always suggest snap before the date, regardless of SCM?

Then it would be something like snap<commitdate/snapdate>.<scm>.<shorthash>.

We're getting into bikeshedding terriory here… but I don't think this is better.
In particular:

$ rpmdev-vercmp 0.5.0+snap2020 0.5.0.post1
0.5.0+snap2020 > 0.5.0.post1

And also, snap<commitdate/snapdate>.<scm>.<shorthash> is 24–27 characters (with a 7–10 digit hash), which is annoying.

So I think it's fine to say that "if you need to cover RHEL7, just use the old system". It's not going away and many people will keep using it anyway because they don't see a good enough reason to switch to the new one.

So I think it's fine to say that "if you need to cover RHEL7, just use the old system". It's not going away and many people will keep using it anyway because they don't see a good enough reason to switch to the new one.

:thumbsup:

then you can immediately move to using Release: 1%{?dist} with no ordering issues.

I don't understand this part. Is there some information missing, such as that we were using Release: 0.N%{?dist} release before?

I don't understand this part. Is there some information missing, such as that we were using Release: 0.N%{?dist} release before?

Yeah, I think it's some leftover from an older convention.

I pushed two new commits:
- reword the sentence about "version 0" to fix the issue mentioned by @churchyard
- say that when supporting RHEL<9 with the same spec file, the traditional approach should be used.

--

I think this is ready for general review and/or merging. Please consider this an official pull request now. Let me know if I should submit a separate ticket somewhere.

• say that when supporting RHEL<9 with the same spec file, the traditional approach should be used.

RHEL 8 also supports tilde and caret.

Let me know if I should submit a separate ticket somewhere.

We have two tickets that this would resolve: #904 and #937

I reworked this part. I realized that everything becomes simple if carets are only used for snapshots, and post-releases simply use a dot as the separator. Apart from some edge cases, a bugfix post-release is just a release.

Looks great now, thanks. 👍

RHEL 8 also supports tilde and caret.

mock -r epel-8-x86_64 --shell 'rpm -q rpm' gives me rpm-4.14.3-13.el8.x86_64, and ^ was added 4.15 according to https://fedoraproject.org/wiki/Changes/RPM-4.15#Detailed_Description. What am I missing?

IIRC support for ^ versioning was backported to rpm in RHEL 8. Neal will correct me if I'm wrong :)

Thanks. I adjusted the last commit to say RHEL7, and removed the explicit mention of rpm versions (I don't think it's useful to go into details of what was backported where).

IIRC support for ^ versioning was backported to rpm in RHEL 8. Neal will correct me if I'm wrong :)

Yes, it was backported some time ago, as I noted in #904 :wink:

If there are not more comments… can this go on the meeting agenda?

Python related note: Python packages release post releases as e.g. 1.2.3post1. Up until now, I'd package that as 1.2.3^post1. Packaging as 1.2.3.post1 is possible as well, however brings all sort of trouble with it (e.g. it is not easily convertible to upstream version simply by stripping tildes and carets). Can we at least package it as 1.2.3post1 or is the dot mandatory?

I don't think anything special needs to happen for 1.2.3post1. It falls squarely into the "Simple versioning" section, like 1.4, 1.4a, 1.4b given in the example. Actually that part of the text wasn't changed, except for cosmetic updates.

This section confused me:

For example, if the same upstream released 0.5.0-post1 as a bugfix version,
this "post-release" should use 0.5.0.post1 in the Version: field.
Note that 0.5.0.post1 sorts lower than both 0.5.1 and 0.5.0.1.

Yeah, but that section is titled "Handling non-sorting versions with tilde, dot, and caret". In the example given in the text "0.5.0-post1" requires special treatment because "-" is a separator between version and release, and we cannot have it in the version field. None of this applies to 1.2.3post1. I think the text is is pretty clear. If you have some suggestion how to make the text clearer, please propose a specific change.

(Would adding a sentence about why "-" is not allowed in that place make things clear?)

Also note, that you could also use _ in place of -, though it does look kind of weird.

Also note, that you could also use _ in place of -, though it does look kind of weird.

Conceptually a dot is better: rpm thinks the dot is a component separator, so 1.2.3.post1 is a separate version with (1, 2, 3, post1). With the underscore, we get (1, 2, 3_post1). This works fine because 3_post sorts later than 3. I think that upstream meant this to be a separate component by separating this with the dash. The fact that there's a conceptual advantage is much less important than the fact that both versions work fine, so I wouldn't care too much if a packager used _, but I think it's still nicer to recommend the dot…

Makes sense to me.

+1 as it is. I don't want to bike shed about details, I want this used in practice :) We can iterate later if needed.

Thanks @zbyszek

+1 from me

I'm 99% sure there's no difference between '_' and '.' ... rpm only cares about ASCII alphanumerics, '~' and '^' ... anything else is the same.

See:

https://github.com/rpm-software-management/rpm/blob/master/rpmio/rpmvercmp.c#L34

Also:

% rpmdev-vercmp abcd_xyz abcd.xyz
abcd_xyz == abcd.xyz

Thanks for picking this up and running with it. +1 from me, though we will need to figure out how to best keep the old document around.

This is approved in today's meeting:

 #action Use tilde and caret in version field (+1:6, 0:0, -1:0)

Thanks for this, merging!

Woohoooo!

I'm 99% sure there's no difference between '_' and '.' ... rpm only cares about ASCII alphanumerics, '~' and '^' ... anything else is the same.

I stand corrected. So yeah, in principle we could use _ instead of . as a replacement character. I would argue that a dot still looks better, but technically the result seems to be same.