Version-string schemes for the Java SE Platform and the JDK

Wed Oct 25 10:17:00 UTC 2017

Mark,

I have only seen universal acclaim on your decision to move to a 
six-month release model for OpenJDK. On the contrast, the suggested 
version change has met a lot of resistance, and disappearingly little 
praise. Yet, there seems to be little reason to make these two into a 
tightly coupled "take it or leave it" package. What could be a rallying 
cause, that would unify the community to work together with shifting up 
the development speed of Java, will instead be sawing the seeds of 
discord. And all for no good reason.

As you well know, a new version scheme was created in JEP 223 for JDK 9 
[1]. This was the result of a thourough analysis, and was grounded in 
discussions with multiple parties on what constitutes a good version 
number.

Let me quote the goals from that JEP:
>
>  *
>
>     Be easily understandable by humans, and easily parsable by programs.
>
>  *
>
>     Align with current industry practices, in particular Semantic
>     Versioning <http://semver.org/>.
>
>  *
>
>     Be adoptable by existing packaging systems and platform-deployment
>     mechanisms including RPM
>     <https://en.wikipedia.org/wiki/RPM_Package_Manager>, dpkg
>     <https://en.wikipedia.org/wiki/Dpkg>, IPS
>     <https://en.wikipedia.org/wiki/Image_Packaging_System>, and the
>     Java Network Launching Protocol (JNLP)
>     <https://en.wikipedia.org/wiki/JNLP>.
>
>  *
>
>     Eliminate the current practice of encoding two types of
>     information in one element of the version string, /i.e./, the
>     minor release number and the security level, which is difficult to
>     decipher and results in skipping many version numbers.
>
>  *
>
>     Provide a simple API for version-string parsing, validation, and
>     comparison.
>

All in all, these are reasonable goals for a versioning scheme, and I 
believe JEP 223 managed to meet these goals.

In contrast, the year-based version schemes you propose fails to meet at 
least the two top-most goals. But even if it were to meet all goals, 
that would still not provide a good reason to change. Just as for all 
other technical changes in Java, there need to be some great enough 
*additional* merit to provide a reason to switch from the existing 
solution to another, new and unproven.

I believe that at times it's good to take a step back, and look at the 
question of relevance [2]. You are providing a lot of arguments for a 
specific type of version format, but I have a hard time finding good 
reasons as to *why* the change of version format is necessary or even 
relevant, given a change in release cadence.

In the rest of this mail, I'll try to extract reasons for deviating from 
status quo (JEP 223), in contrast to reasons for arguing for one type or 
other of new version schemes, and add some comments.

On 2017-10-19 17:08, mark.reinhold at oracle.com wrote:
>      First: Compatibility is, itself, multi-dimensional and therefore
>      difficult to encode into a simple sequence of numerals.  What counts
>      as an incompatible change?
Semantic Versioning (semver) uses this rule: "increment the MAJOR 
version when you make incompatible API changes". [3] As you say, there 
are gray areas with the concept of "incompatible API changes" in the 
context of Java and the JDK, but that does not mean that this is a bad 
rule, only that it needs to be applied judiciously.

Once again, let's look at what's currently governing Java version 
numbers. JEP 223 provides this definition: "The major version number, 
incremented for a major release that contains significant new features" 
[4]. In a break with semver, there is actually no requirements for 
breaking compatibility to bump the major version number, just that 
"significant new features" are added. This is a requirement that I 
believe will still be just as applicable for releases on a six month 
cadence. (If we're not able to add significant new features between 
releases, we have a much more serious problems than the version string!)

>      Second: The compatibility of a particular release with any of its
>      predecessors depends upon the set of features in that release.  In a
>      time-based release model, however, the set of features is not known
>      until late in each release cycle, after the final feature is merged.
>      This complicates discussions of any specific release and the tracking
>      of changes in JIRA and related systems.  If, e.g., we use the leading
>      numerals of version numbers to encode compatibility in the usual way,
>      with the first numeral increasing only when incompatible changes are
>      made, then would the March 2018 release be version 9.1, or 10?  We
>      can't know until some time in December 2017, when the release closes
>      for stabilization.
>
>      We could address this problem by establishing secondary, time-based
>      labels for releases, but that would be awkward and could lead to even
>      more confusion.
The question you're discussing here is "what is convenient for the 
developers and release managers of OpenJDK", not "what is convenient for 
the users of OpenJDK". The number of the former outweight the latter in 
orders of magnitute, and so it's the only impact that's relevant in this 
discussion.

> This would be a departure from past releases, in which we've used version
> numbers that roughly encode both compatibility and significance.  It is,
> however, a better fit for a strict, time-based release model since the
> version number of any particular release is known well in advance.
Here's one of the few actual arguments for the reason to actually change 
the version string that I've been able to find. I will not challenge 
your conclusion (that a time-based versioning scheme will be a better 
fit for a time-based release model), but I do challenge the relevance of 
this argument. Why is it important to know the version number of a 
particular release in advance? To whom is it important? Release 
managers, or the users of Java?And even if it is important (which I 
seriously doubt), is it important enough to upend the current scheme?

/Magnus

[1] http://openjdk.java.net/jeps/223
[2] https://en.wikipedia.org/wiki/Ignoratio_elenchi
[3] http://semver.org/
[4] http://openjdk.java.net/jeps/223#Version-numbers