Summary
-------

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


Goals
-----

  - Recast the version-number scheme introduced by [JEP 223][223] so that
    it better fits time-based release models that define _feature
    releases_, which can contain new features, and _update releases_,
    which only fix bugs.

  - Allow for time-based release models other than the
    [current model][ff-prop], with a different cadence or with _interim_
    releases smaller than feature releases but larger than update
    releases.

  - Preserve compatibility with the overall JEP 223 version-string
    scheme.

  - Make it easy for a developer or end user to figure out how old a
    release is, so that they can judge whether to upgrade it to a newer
    release with the latest security fixes and, possibly, additional
    features.

  - Provide a way for an implementor to indicate that a release is part
    of a series of releases for which the implementor offers long-term
    support.

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

[223]: http://openjdk.java.net/jeps/223
[ff-prop]: https://mreinhold.org/blog/forward-faster#Proposal


Non-Goals
---------

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

It is not a goal to revise the version-report output of command-line
tools other than the `java` launcher.  Doing so is desirable but not
critical, and can be done later on.


Motivation
----------

The version-string scheme introduced by [JEP 223][223] was a significant
improvement over that of the past.  That scheme is not, however,
well-suited to the future, in which we intend to ship new releases of the
Java SE Platform and the JDK on a
[strict, six-month cadence][ff-prop].

The main difficulty with the JEP 223 scheme is that a release's version
number encodes its significance and compatibility relative to its
predecessors.  In a time-based release model, however, these qualities
are not known in advance.  They are subject to change throughout a
release'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 a
release of the JDK, or builds or uses components on top of it, will have
to speak initially of the release's ship date and then switch to speaking
of the version number, once it is known.  Developers who maintain
libraries, frameworks, and tools will have to be prepared to change code
that 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 version
numbers to encode not compatibility and significance but, rather, the
passage of time, in terms of release cycles.  This is a better fit for
time-based release models since each release cycle, and thus each
release's version number, is always known well in advance.


Description
-----------

### Version numbers

A _version number_, `$VNUM`, is a non-empty sequence of elements
separated by period characters (U+002E).  An element is either zero, or
an unsigned integer numeral without leading zeros.  The final element of
a version number must not be zero.  When an element is incremented, all
subsequent 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 are
assigned specific meanings, as follows:

    $FEATURE.$INTERIM.$UPDATE.$PATCH

  - <a id="FEATURE">`$FEATURE`</a> &#x2014; 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 of
    time.  Incompatible changes may be made when justified.  (Formerly
    `$MAJOR`.)

  - <a id="INTERIM">`$INTERIM`</a> &#x2014; The interim-release counter,
    incremented for non-feature releases that contain compatible bug
    fixes and enhancements but no incompatible changes, no feature
    removals, and no changes to standard APIs.  (Formerly `$MINOR`.)

  - <a id="UPDATE">`$UPDATE`</a> &#x2014; The update-release counter,
    incremented for compatible update releases that fix security issues,
    regressions, and bugs in newer features.  (Formerly `$SECURITY`, but
    with a non-trivial incrementation rule.)

  - <a id="PATCH">`$PATCH`</a> &#x2014; The emergency patch-release
    counter, incremented only when it's necessary to produce an emergency
    release to fix a critical issue.  (Using an additional element for
    this purpose minimizes disruption to both developers and users of
    in-flight update releases.)

The fifth and later elements of version numbers are reserved for use by
downstream consumers of the JDK code base.  The fifth element may be used
to, _e.g._, identify implementor-specific patch releases.

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

The sequence of numerals in a version number is compared to another such
sequence in numerical, pointwise fashion; _e.g._, `10.0.4` is less than
`10.1.2`.  If one sequence is shorter than another then the missing
elements of the shorter sequence are considered to be less than the
corresponding elements of the longer sequence; _e.g._, `10.0.2` is less
than `10.0.2.1`.

### Version numbers in the six-month release model

Under the [six-month release model][ff-prop] the elements of version
numbers vary as follows:

  - `$FEATURE` is incremented every six months: The March 2018 release is
     JDK&nbsp;10, the September 2018 release is JDK&nbsp;11, and so
     forth.

  - `$INTERIM` is always zero, since the six-month model does not include
    interim releases.  We reserve it here for flexibility, so that a
    future revision to the release model could include such releases and
    say 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, in
    essence, interim releases, and would have been numbered 4.1 and 4.2
    under this scheme.

  - `$UPDATE` is incremented one month after `$FEATURE` is incremented,
    and every three months thereafter: The April 2018 release is JDK
    10.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 two
significant features, and for update releases never to include
incompatible changes.  In combination with the fact that `$INTERIM` is
always zero, in practice this scheme will often define version numbers
that are not much different from what the JEP 223 scheme would have
defined.

### Version strings

The overall format of version strings is the same as that defined in
[JEP 223][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 a
build number, and `$OPT` is optional build information.

If a release is part of a series of releases for which an implementor
offers 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 displayed
prominently in the output of `java --version`, _etc_., more on which
below.

### API

We revise the `Runtime.Version` API [defined by JEP 223][rv-api] as
follows:

  - Add four new `int`-returning accessor methods for the principal
    components of version numbers as defined above: `feature()`,
    `interim()`, `update()`, and `patch()`.

  - Redefine the existing accessor methods `major()`, `minor()`, and
    `security()` to return the same values as `feature()`, `interim()`,
    and `update()`, respectively.

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

[rv-api]: https://docs.oracle.com/javase/9/docs/api/java/lang/Runtime.Version.html

### System properties

To the system properties mentioned in [JEP 223][223] we add two new
properties:

  - `java.version.date` &#x2014; The general-availability (GA) date of
    this release, in ISO-8601 YYYY-MM-DD format.  For early-access
    releases this will be the intended GA date, _i.e._, some date in the
    future.

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

  - `java.vendor.version` &#x2014; An implementor-specific product
    version string, optionally assigned by the individual or organization
    that produces a specific implementation.  If not assigned at build
    time then it has no value; otherwise, its value is a non-empty string
    that matches the regular expression `\p{Graph}+`.

This new property makes it possible for implementors to provide
additional version information as may be necessary to align with related
products.  An implementor whose product line uses, _e.g._, date-based
versions of the form `$YEAR.$MONTH` could set this property accordingly
so that their JDK releases are clearly related to their other releases.
(This property is named `java.vendor.version` rather than the more
obvious `java.implementor.version` in order to be consistent with the
[existing system properties][props] whose names include `vendor`.)

[props]: https://docs.oracle.com/javase/9/docs/api/java/lang/System.html#getProperties--

### Launcher

The `java` launcher will display version strings and system properties as
follows, for a hypothetical build 13 of JDK 10.0.1:

    $ java --version
    openjdk 10.0.1 2018-04-19
    OpenJDK 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 --version
    openjdk 11 2018-09-20 LTS
    OpenJDK 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 a
JDK 11 LTS build then it would be displayed:

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

<a id="Launcher-detail">In detail</a>, the output of the `java`
launcher's version-report options will be formatted as follows, where
`${LTS}` expands to `"\u0020LTS"` if the first three characters of `$OPT`
are `"LTS"`, and `${JVV}` expands to `"\u0020${java.vendor.version}"` if
that system property is defined:

    $ java --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 --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-version
    openjdk ${java.runtime.version}
    $ 
    
    $ java -version
    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 -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 -fullversion
    openjdk full version \"${java.runtime.version}\"
    $ 

### `@since` JavaDoc tag

The value used with the `@since` JavaDoc tag continues to be aligned with
the system property `java.specification.version`, hence APIs introduced
in JDK&nbsp;10 will be tagged `@since 10`.

### Mercurial changeset tags

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

### Build configuration and output

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

    --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` and `VERSION_PATCH`,
since they already exist.)

The `release` file written into the root of a JDK image will, in addition
to defining the existing `JAVA_VERSION` variable, also define
`JAVA_VERSION_DATE` with the value of the `java.version.date` system
property, and `IMPLEMENTOR_VERSION` with the value of the
`java.vendor.version` system property, if defined.


Alternatives
------------

The [proposal for the six-month time-based release model][ff-prop]
suggested that the version strings of feature releases be of the form
`$YEAR.$MONTH`.  Thus next year's March release would be 18.3, the
September release would be 18.9, and so on each year.

After reasonable objections were raised against this scheme we
[reviewed the various types of information encoded in version numbers and suggested some alternatives][jd-1],
then [summarized and responded to the discussion that followed][jd-2],
and finally [published a proposal][jd-3] that was well received and hence
became the basis for this JEP.

[jd-1]: http://mail.openjdk.java.net/pipermail/jdk-dev/2017-October/000007.html
[jd-2]: http://mail.openjdk.java.net/pipermail/jdk-dev/2017-November/000088.html
[jd-3]: http://mail.openjdk.java.net/pipermail/jdk-dev/2017-November/000089.html


Testing
-------

This newer version-string scheme is largely compatible with that defined
by [JEP 223][223], so testing should be straightforward.  The principal
difference is the potential use of the fourth element for emergency patch
releases, which may require some new unit-test cases.  Changes to the
relevant build-configuration options will require straightforward manual
testing.


Risks and Assumptions
---------------------

The changes described here introduce three minor incompatibilities:

  - [JEP 223][223] specifies the `security()` method of the
    `Runtime.Version` API to return the value of the `$SECURITY` element
    of the version number.  That element is not incremented when the
    element that precedes it, `$MINOR`, is incremented.  This proposal
    renames the `$SECURITY` element to `$UPDATE` and clears that element
    whenever the element that precedes it, `$INTERIM` (formerly
    `$MINOR`), is incremented.  The redefinition of `security()` in terms
    of `update()` is therefore, in theory, an incompatible change.  This
    API was introduced in JDK 9, however, and no releases of JDK 9 with a
    non-zero value of `$MINOR` are envisioned, so in practice this change
    should have minimal impact.

  - The output of the `java` launcher's version-report options now
    includes the version date at the end of the first line, possibly
    followed by `"\u0020LTS"`.  Existing code that parses this output
    under the assumption that the last token on the line is the version
    number may require adjustment.

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