Summary

Revise the version-string scheme of the Java SE Platform and the JDK, andrelated versioning information, for present and future time-based releasemodels.

Goals

• Recast the version-number scheme introduced byJEP 223 so thatit better fits time-based release models that definefeaturereleases, which can contain new features, andupdate releases,which only fix bugs.

• Allow for time-based release models other than thecurrent model, with a different cadence or withinterimreleases smaller than feature releases but larger than updatereleases.

• Preserve compatibility with the overall JEP 223 version-stringscheme.

• Make it easy for a developer or end user to figure out how old arelease is, so that they can judge whether to upgrade it to a newerrelease with the latest security fixes and, possibly, additionalfeatures.

• Provide a way for an implementor to indicate that a release is partof a series of releases for which the implementor offers long-termsupport.

• Provide a way for an implementor to include and display anadditional, implementor-specific version string in order to align arelease with related products.

Non-Goals

It is not a goal to revise the existing version-string scheme toaccommodate requirements other than those related to time-based releasemodels.

It is not a goal to revise the version-report output of command-linetools other than thejava launcher. Doing so is desirable but notcritical, and can be done later on.

Motivation

The version-string scheme introduced byJEP 223 was a significantimprovement over that of the past. That scheme is not, however,well-suited to the future, in which we intend to ship new releases of theJava SE Platform and the JDK on astrict, six-month cadence.

The main difficulty with the JEP 223 scheme is that a release's versionnumber encodes its significance and compatibility relative to itspredecessors. In a time-based release model, however, these qualitiesare not known in advance. They are subject to change throughout arelease's development cycle, until the final feature is integrated.A release's version number is therefore also not known in advance.

With JEP 223's semantics of version numbers, everyone who works on arelease of the JDK, or builds or uses components on top of it, will haveto speak initially of the release's ship date and then switch to speakingof the version number, once it is known. Developers who maintainlibraries, frameworks, and tools will have to be prepared to change codethat inspects version numbers late in each and every JDK release cycle.This is awkward and confusing for all involved.

The principal change proposed here is, therefore, to recast versionnumbers to encode not compatibility and significance but, rather, thepassage of time, in terms of release cycles. This is a better fit fortime-based release models since each release cycle, and thus eachrelease's version number, is always known well in advance.

Description

Version numbers

Aversion number,$VNUM, is a non-empty sequence of elementsseparated by period characters (U+002E). An element is either zero, oran unsigned integer numeral without leading zeros. The final element ofa version number must not be zero. When an element is incremented, allsubsequent elements are removed. The format is:

[1-9][0-9]*((\.0)*\.[1-9][0-9]*)*

The sequence may be of arbitrary length but the first four elements areassigned specific meanings, as follows:

$FEATURE.$INTERIM.$UPDATE.$PATCH

• $FEATURE — The feature-release counter,incremented for every feature release regardless of release content.Features may be added in a feature release; they may also be removed,if advance notice was given at least one feature release ahead oftime. Incompatible changes may be made when justified. (Formerly$MAJOR.)

• $INTERIM — The interim-release counter,incremented for non-feature releases that contain compatible bugfixes and enhancements but no incompatible changes, no featureremovals, and no changes to standard APIs. (Formerly$MINOR.)

• $UPDATE — The update-release counter,incremented for compatible update releases that fix security issues,regressions, and bugs in newer features. (Formerly$SECURITY, butwith a non-trivial incrementation rule.)

• $PATCH — The emergency patch-releasecounter, incremented only when it's necessary to produce an emergencyrelease to fix a critical issue. (Using an additional element forthis purpose minimizes disruption to both developers and users ofin-flight update releases.)

The fifth and later elements of version numbers are reserved for use bydownstream consumers of the JDK code base. The fifth element may be usedto,e.g., identify implementor-specific patch releases.

A version number never has trailing zero elements. If an element and allthose that follow it logically have the value zero then all of them areomitted.

The sequence of numerals in a version number is compared to another suchsequence in numerical, pointwise fashion;e.g.,10.0.4 is less than10.1.2. If one sequence is shorter than another then the missingelements of the shorter sequence are considered to be less than thecorresponding elements of the longer sequence;e.g.,10.0.2 is lessthan10.0.2.1.

Version numbers in the six-month release model

Under thesix-month release model the elements of versionnumbers vary as follows:

• $FEATURE is incremented every six months: The March 2018 release isJDK 10, the September 2018 release is JDK 11, and soforth.

• $INTERIM is always zero, since the six-month model does not includeinterim releases. We reserve it here for flexibility, so that afuture revision to the release model could include such releases andsay that JDK$N.1 and JDK$N.2 are compatible upgrades of JDK$N. As examples, the JDK 1.4.1 and 1.4.2 releases were, inessence, interim releases, and would have been numbered 4.1 and 4.2under this scheme.

• $UPDATE is incremented one month after$FEATURE is incremented,and every three months thereafter: The April 2018 release is JDK10.0.1, the July release is JDK 10.0.2, and so forth.

We do expect most feature releases to contain at least one or twosignificant features, and for update releases never to includeincompatible changes. In combination with the fact that$INTERIM isalways zero, in practice this scheme will often define version numbersthat are not much different from what the JEP 223 scheme would havedefined.

Version strings

The overall format of version strings is the same as that defined inJEP 223. A version string is a version number,$VNUM,possibly followed by pre-release, build, and other optional information,one of:

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

where$PRE is a pre-release identifier (e.g.,ea),$BUILD is abuild number, and$OPT is optional build information.

If a release is part of a series of releases for which an implementoroffers long-term support then the value of$OPT should start with"LTS", e.g., 11.0.2+13-LTS. This will cause"LTS" to be displayedprominently in the output ofjava --version,etc., more on whichbelow.

API

We revise theRuntime.Version APIdefined by JEP 223 asfollows:

• Add four newint-returning accessor methods for the principalcomponents of version numbers as defined above:feature(),interim(),update(), andpatch().

• Redefine the existing accessor methodsmajor(),minor(), andsecurity() to return the same values asfeature(),interim(),andupdate(), respectively.

• Deprecate the existing accessor methods, but not for removal, withadvice to use the corresponding new methods. This will help make thenew semantics of version numbers clear to developers.

System properties

To the system properties mentioned inJEP 223 we add two newproperties:

• java.version.date — The general-availability (GA) date ofthis release, in ISO-8601 YYYY-MM-DD format. For early-accessreleases this will be the intended GA date,i.e., some date in thefuture.

This new property makes it easy to figure out how old a release is, sothat as a user you can understand how far behind you are. It alsoreflects the security level of the release: A given GA release containsthe latest security fixes if its version date is no earlier than that ofany other GA release.

• java.vendor.version — An implementor-specific productversion string, optionally assigned by the individual or organizationthat produces a specific implementation. If not assigned at buildtime then it has no value; otherwise, its value is a non-empty stringthat matches the regular expression\p{Graph}+.

This new property makes it possible for implementors to provideadditional version information as may be necessary to align with relatedproducts. An implementor whose product line uses,e.g., date-basedversions of the form$YEAR.$MONTH could set this property accordinglyso that their JDK releases are clearly related to their other releases.(This property is namedjava.vendor.version rather than the moreobviousjava.implementor.version in order to be consistent with theexisting system properties whose names includevendor.)

Launcher

Thejava launcher will display version strings and system properties asfollows, for a hypothetical build 13 of JDK 10.0.1:

$ java --versionopenjdk 10.0.1 2018-04-19OpenJDK Runtime Environment (build 10.0.1+13)OpenJDK 64-Bit Server VM (build 10.0.1+13, mixed mode)$

Similarly, for a hypothetical build 42 of JDK 11, an LTS release:

$ java --versionopenjdk 11 2018-09-20 LTSOpenJDK Runtime Environment (build 11+42-LTS)OpenJDK 64-Bit Server VM (build 11+42-LTS, mixed mode)$

If an implementor assigns a vendor version string of,e.g.,18.9 to aJDK 11 LTS build then it would be displayed:

$ java --versionopenjdk 11 2018-09-20 LTSOpenJDK Runtime Environment 18.9 (build 11+42-LTS)OpenJDK 64-Bit Server VM 18.9 (build 11+42-LTS, mixed mode)$

In detail, the output of thejavalauncher's version-report options will be formatted as follows, where${LTS} expands to"\u0020LTS" if the first three characters of$OPTare"LTS", and${JVV} expands to"\u0020${java.vendor.version}" ifthat system property is defined:

$ java --versionopenjdk ${java.version} ${java.version.date}${LTS}${java.runtime.name}${JVV} (build ${java.runtime.version})${java.vm.name}${JVV} (build ${java.vm.version}, ${java.vm.info})$ $ java --show-version < ... >openjdk ${java.version} ${java.version.date}${LTS}${java.runtime.name}${JVV} (build ${java.runtime.version})${java.vm.name}${JVV} (build ${java.vm.version}, ${java.vm.info})[ ... ]$ $ java --full-versionopenjdk ${java.runtime.version}$ $ java -versionopenjdk version \"${java.version}\" ${java.version.date}${LTS}${java.runtime.name}${JVV} (build ${java.runtime.version})${java.vm.name}${JVV} (build ${java.vm.version}, ${java.vm.info})$ $ java -showversion < ... >openjdk version \"${java.version}\" ${java.version.date}${LTS}${java.runtime.name}${JVV} (build ${java.runtime.version})${java.vm.name}${JVV} (build ${java.vm.version}, ${java.vm.info})[ ... ]$ $ java -fullversionopenjdk full version \"${java.runtime.version}\"$

@since JavaDoc tag

The value used with the@since JavaDoc tag continues to be aligned withthe system propertyjava.specification.version, hence APIs introducedin JDK 10 will be tagged@since 10.

Mercurial changeset tags

The general syntax for the Mercurial tags that identify promoted buildsis unchanged:jdk\-$VNUM\+$BUILD.

Build configuration and output

Three existing version-related configuration options will be deprecatedand hence ignored, and the related Make variables will no longer bedefined:

--with-version-major          VERSION_MAJOR--with-version-minor          VERSION_MINOR--with-version-security       VERSION_SECURITY

Five new options, and corresponding variables, will be defined:

--with-version-feature        VERSION_FEATURE--with-version-interim        VERSION_INTERIM--with-version-update         VERSION_UPDATE--with-version-date           VERSION_DATE--with-vendor-version-string  VENDOR_VERSION_STRING

(There is no need to define--with-version-patch andVERSION_PATCH,since they already exist.)

Therelease file written into the root of a JDK image will, in additionto defining the existingJAVA_VERSION variable, also defineJAVA_VERSION_DATE with the value of thejava.version.date systemproperty, andIMPLEMENTOR_VERSION with the value of thejava.vendor.version system property, if defined.

Alternatives

Theproposal for the six-month time-based release modelsuggested that the version strings of feature releases be of the form$YEAR.$MONTH. Thus next year's March release would be 18.3, theSeptember release would be 18.9, and so on each year.

After reasonable objections were raised against this scheme wereviewed the various types of information encoded in version numbers and suggested some alternatives,thensummarized and responded to the discussion that followed,and finallypublished a proposal that was well received and hencebecame the basis for this JEP.

Testing

This newer version-string scheme is largely compatible with that definedbyJEP 223, so testing should be straightforward. The principaldifference is the potential use of the fourth element for emergency patchreleases, which may require some new unit-test cases. Changes to therelevant build-configuration options will require straightforward manualtesting.

Risks and Assumptions

The changes described here introduce three minor incompatibilities:

• JEP 223 specifies thesecurity() method of theRuntime.Version API to return the value of the$SECURITY elementof the version number. That element is not incremented when theelement that precedes it,$MINOR, is incremented. This proposalrenames the$SECURITY element to$UPDATE and clears that elementwhenever the element that precedes it,$INTERIM (formerly$MINOR), is incremented. The redefinition ofsecurity() in termsofupdate() is therefore, in theory, an incompatible change. ThisAPI was introduced in JDK 9, however, and no releases of JDK 9 with anon-zero value of$MINOR are envisioned, so in practice this changeshould have minimal impact.

• The output of thejava launcher's version-report options nowincludes the version date at the end of the first line, possiblyfollowed by"\u0020LTS". Existing code that parses this outputunder the assumption that the last token on the line is the versionnumber may require adjustment.

• The output of thejava launcher's--version,--show-version,-version, and-showversion options will include the value of thejava.vendor.version system property on the second and third lines,if that value differs from that of thejava.version. Existing codethat parses this output may require adjustment.