JEP 223: New Version-String Scheme

Fri Nov 7 12:39:11 UTC 2014

Great work! I've really been looking forward to this! :-) The old 
versioning system (or lack thereof) is a constant source of annoyance in 
the build system.

I think the proposal is overall well designed and well thought out. I'm 
also glad to see the close alignment with semantic versioning and the 
effort spent at making the string easy to parse.

The only thing I stumbled on was some details on the optional 
post-version number data, and a problem with regard to the parsability. 
More specifically:

(Quotes are from the JEP.)

> When comparing two version strings, a string with a pre-release 
> identifier is always less than one with an equal $VNUM but no such 
> identifier. Pre-release identifiers are compared numerically when they 
> consist only of digits, and lexicographically otherwise.

The first part of that rule is reasonable, and aligns with semantic 
versioning (item 9).

I'm not so sure about the second part, about comparing pre-release 
identifiers. First of all, is it necessary? If we are prepared to accept 
that there exists byte-wise different version strings that does not 
differ in order comparison (which is how I read the JEP with regard to 
$BUILD and $OPT), then maybe we should do so for $PRE as well?

For instance, is it obvious that you can order "9.0.0-ea+30" and 
"9.0.0-internal+30" in any meaningful way?

And if we really do want to keep an ordering scheme on $PRE, the current 
description could at least be improved. Is the numerical comparison 
supposed to be used when comparing two strictly numerical strings, but 
not if one of them is non-numeric? But would that mean that "9.0.0-3000" 
is newer than "9.0.0-300" but not newer than "9.0.0-300beta"?

And comparing non-numeric $PRE strings in lexicographic order does not 
really make sense. If "ea" is supposed to be ordered ahead of 
"internal", then that's just by pure coincidence. If so, a "9.0.0-adhoc" 
build would order above "9.0.0-ea", even though the intent of "adhoc" is 
the same as of "internal".

Instead, I propose that for two version strings with two different $PRE 
parts present, no ordering difference should be made.

> When comparing two version strings the value of $BUILD, if present, is 
> always ignored.

Here, I'd actually like to suggest the reverse. While there is to me no 
reason to believe any of "9.0.0-ea+30" and "9.0.0-internal+30" to be 
ordered ahead of the other, I do believe there is good reason to 
consider "9.0.0-ea+30" a higher version than "9.0.0-ea+29".

More specifically, I'd propose that for two version strings with 
identical version numbers and $PRE strings, the numerical value of 
$BUILD will determine versioning order. For different $PRE strings, as 
before, no ordering difference should be made.

> $OPT, matching ([-a-zA-Z0-9]+) --- Additional build information, if 
> desired. In the case of an internal build this will often contain the 
> date and time of the build.

I'd like to request the underscore (_) sign to be added to the list of 
allowed characters in $OPT. It is often useful to be able to separate 
parts of string with _ as well as -, especially since $OPT will 
typically be used to help developers annotate a build. That will allow 
having an $OPT string such as ihse-version-test_2014-11-07_11-05.

And last, but not least, the suggested version string format:

> $VNUM(-$PRE)?(\+$BUILD)?(-$OPT)?

is unfortunately not unambiguously parsable. :-( For instance, 
"9.0.0-foo"  could mean either $PRE=foo or $OPT=foo, since both $PRE and 
$BUILD is optional.

There are several ways to solve this. Some suggestions:

1) Requiring that either $PRE or $BUILD must be present if $OPT should 
be allowed.

I think it would be unfortunate to make such requirements, since it will 
only lead back to the current practice of having a dummy value e.g. "00" 
for build in cases were it does not make sense to have a $BUILD value.

2) Requiring that the "+" (the $BUILD marker) must be present if $OPT is 
present, even if $BUILD is empty.

For instance, 9.0.0+-foo-opt. While this would be technically in line 
with the semantic versioning specification, in my opinion, this looks 
just too ugly.

3) Using a different marker than "-" for introducing $OPT, e.g. underscore.

For instance, 9.0.0_foo-opt or 9.0.0-ea-_foo-opt. I think this is a 
better solution than the ones above, but it is not ideal. It also 
differs from the semantic versioning rules.

4) Adjusting the format of a version string to 
$VNUM(-$PRE)?(-$BUILD)?(\+$OPT)?, with the additional requirement that 
$PRE is a-z only.

For instance, 9.0.0-ea-13+test-run-2 or 9.0.0-13+ihse-debug. This would 
be my preferred choice. If $PRE is restricted to a-zA-Z only, and $BUILD 
is restricted to 0-9 only, it would be possible to unambigiously parse 
such a string.

I also believe it matches the intent and examples of semantic versioning 
better. In this case, the combination ($PRE)?(-$BUILD) would correspond 
to the "pre-release identifier" of section 9 in the semantic versioning 
specification, and $OPT would correspond to the "build metadata" of 
section 10. I believe this is a closer match to the intent, than 
considering $BUILD (together with $OPT) part of the build metadata (as 
the current JEP proposal does). Limiting $PRE to a-z only does not seem 
like an a problematic restriction, since the intent (I guess) is to use 
it for a limited set of well-known "tags" like ea or internal, and not 
as a free-form field like $OPT.

Finally, it is trivial to write a regular expression that matches this 
format precisely. That is not the case for all of the other suggested 
solutions.

To fully embrace the intentions of the semantic versioning 
specification, the $PRE and $BUILD should probably be separated by a 
dot, e.g. 9.0.0-ea.13+test-run-2. But this is not required to follow the 
specification and make the version string possible to parse 
unambiguously, and in my personal opinion it makes it harder to read and 
understand.

/Magnus

On 4 November 2014 22:05, <mark.reinhold at oracle.com> wrote:
>
> New JEP Candidate: http://openjdk.java.net/jeps/223
>
> - Mark