JEP 223: New Version-String Scheme
Magnus Ihse Bursie
magnus.ihse.bursie at oracle.com
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
More information about the platform-jep-discuss
mailing list