Proposal: Newer version-string scheme for the Java SE Platform and the JDK

Thu Nov 2 21:08:20 UTC 2017

Overall, this is a pretty good scheme, thanks for listening.

I'd argue however that the references to six months in $FEATURE and
three months in $UPDATE are unhelpful. Those cadences may be the
cadences around which the scheme is intended to work today, but this
version scheme would also work with other cadences, such as
alternating 5 month / 7 month for $FEATURE and 2 month for $UPDATE. As
such, I'd suggest you don't conflate the two. Instead, separate the
definitions of each numeral from the particular time-boxes you
currently intend.

For example:
"The feature-release counter, incremented every six months regardless
of release content"
becomes
"The feature-release counter, incremented for each time-boxed release,
regardless of release content"

"The update-release counter, incremented every three months for..."
becomes
"The update-release counter, incremented for each release of..."

And then at the end noting that time-boxed $FEATURE releases are
currently every six months and $UPDATE releases every 3 months.

The proposal does not indicate what happens with the class file
version, but replies on Twitter indicate an intention to update that
number with each feature release. IMO this would be a mistake, as
changing the class file number has a knock on effect on a lot of
low-level downstream tools that often take months to update, with
nasty impacts on the ability to adopt a feature release. As such, I
*strongly* argue that the class file version should only change when
it is required to do so. This will occur naturally when a change is
merged into master that requires a new version, so there is no impact
on process that I can see.

I have separate concerns regarding LTS in general and feature removals
in particular, but that deserves a separate thread.

thanks
Stephen

On 2 November 2017 at 15:11,  <mark.reinhold at oracle.com> wrote:
> Here's a specific proposal, with commentary, and two questions.
>
> Summary: This is a time-based scheme, similar to alternative (C) in my
> earlier note [1][2] but even closer to the current scheme as defined in
> JEP 223 [3].  It's hence even less likely to surprise, and should be
> easier to adopt.
>
>                                   * * *
>
> Version numbers
> ---------------
>
> A version number, $VNUM, is a sequence of numerals of arbitrary length,
> separated by period characters.  The first four numerals are interpreted
> as follows:
>
>     $FEATURE.$INTERIM.$UPDATE.$EMERG
>
> where:
>
>   - $FEATURE -- The feature-release counter, incremented every six months
>     regardless of release content.  Thus the March 2018 release is 10,
>     the September 2018 release is 11, and so forth.  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.)
>
>   - $INTERIM -- 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.  This counter is always zero for the current six-month release
>     model.  We reserve it here to leave flexibility for the future, so
>     that some future release model could say that JDK $N.1 and JDK $N.2
>     are compatible upgrades of JDK $N.  Leaving this counter at zero for
>     the current model has an additional benefit in that it increases the
>     degree to which version numbers continue to reflect, roughly, both
>     compatibility and significance.  (Formerly $MINOR.)
>
>   - $UPDATE -- The update-release counter, incremented every three months
>     for compatible update releases that fix security issues, regressions,
>     and bugs in newer features.  Thus the April 2018 release is 10.0.1,
>     the July release is 10.0.2, and so forth.  (Formerly $SECURITY, but
>     with a non-trivial incrementation rule.)
>
>   - $EMERG -- The emergency-release counter, incremented only when it's
>     necessary to produce an emergency release to fix an urgent security
>     issue.  Using an additional numeral for this purpose minimizes the
>     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.
>
> This is primarily a time-based scheme, since $FEATURE is incremented
> every six months regardless of release content and, for each feature
> release, $UPDATE is incremented every three months.  We do expect most
> feature releases to contain at least one or two significant features,
> and never to ship interim releases under the new release model, so in
> practice this scheme will often be very similar to a compatibility- or
> significance-oriented scheme like that of JEP 223.  JDK 10 is a feature
> release, JDK 10.0.1 and 10.0.2 are update releases with compatible bug
> fixes, and there is no interim JDK 10.1 release since in this model the
> next opportunity to add features is JDK 11.
>
> Version strings
> ---------------
>
> The overall format of version strings is unchanged.  A version string is
> a version number, $VNUM, optionally 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.
>
> Implementors who offer long-term support for a release should use an $OPT
> string that starts with "lts", e.g., 11.0.2+13-lts.
>
> System properties
> -----------------
>
> To the system properties mentioned in JEP 223 we add one new property:
>
>   java.version.date -- The GA date of this version, in ISO-8601
>   YYYY-MM-DD format.  For EA releases this will be the intended GA
>   date, i.e., some date in the future.  This value is not part of the
>   version string per se, but it will be displayed when useful and can
>   be retrieved via a new method on the `Runtime.Version` API.
>
> 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.
>
> 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 you've read this far, two questions:
>
>   (1) Bearing in mind that no version-string scheme is ideal,
>       is this scheme acceptable?
>
>   (2) If this scheme is not acceptable then please explain why,
>       and identify exactly what you would change.
>
> Ground rules, as before: I'll give much greater weight to your first
> reply to this message than to any other, I'll ignore replies-to-replies,
> and I'll heavily discount replies that quote more text than add new text
> of their own.
>
> I'll summarize relevant replies in about a week, and then draft a JEP.
>
> - Mark
>
>
> [1] http://mail.openjdk.java.net/pipermail/jdk-dev/2017-October/000007.html
> [2] http://mail.openjdk.java.net/pipermail/jdk-dev/2017-November/000088.html
> [3] http://openjdk.java.net/jeps/223