JEP 322: Time-Based Release VersioningJEP 322: Time-Based Release VersioningOwnerMark ReinholdTypeFeatureScopeSEStatusClosed / DeliveredRelease10Componentcore-libs / java.langDiscussionjdk dash dev at openjdk dot java dot netEffortMDurationSReviewed byAlan Bateman, Alex Buckley, Dalibor Topic, Iris Clark, John RoseEndorsed byBrian GoetzCreated2017/11/30 17:51Updated2021/01/06 22:40Issue8192828Summary
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 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, 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.


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 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.
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


$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 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.  (Formerly $MINOR.)


$UPDATE — 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.)


$PATCH — 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 the elements of version
numbers vary as follows:


$FEATURE is incremented every six months: The March 2018 release is
JDK 10, the September 2018 release is JDK 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.  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 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.


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

java.version.date — 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 — 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 whose names include vendor.)
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)
$
In detail, 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 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
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,
then summarized and responded to the discussion that followed,
and finally published a proposal that was well received and hence
became the basis for this JEP.
Testing
This newer version-string scheme is largely compatible with that defined
by JEP 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 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.


InstallingContributingSponsoringDevelopers' GuideVulnerabilitiesJDK GA/EA BuildsMailing listsWiki
                      · IRCBylaws · CensusLegalWorkshopJEP ProcessSource codeMercurialGitHubToolsGitjtreg harnessGroups(overview)AdoptionBuildClient LibrariesCompatibility & Specification ReviewCompilerConformanceCore LibrariesGoverning BoardHotSpotIDE Tooling & SupportInternationalizationJMXMembersNetworkingPortersQualitySecurityServiceabilityVulnerabilityWebProjects(overview,
      archive)AmberBabylonCRaCCaciocavalloClosuresCode ToolsCoinCommon VM InterfaceCompiler GrammarDetroitDevelopers' GuideDevice I/ODukeGalahadGraalIcedTeaJDK 7JDK 8JDK 8 UpdatesJDK 9JDK
      (…,
       21,
       22,
       23)JDK UpdatesJavaDoc.NextJigsawKonaKullaLambdaLanaiLeydenLilliputLocale EnhancementLoomMemory Model UpdateMetropolisMission ControlMulti-Language VMNashornNew I/OOpenJFXPanamaPenrosePort: AArch32Port: AArch64Port: BSDPort: HaikuPort: Mac OS XPort: MIPSPort: MobilePort: PowerPC/AIXPort: RISC-VPort: s390xPortolaSCTPShenandoahSkaraSumatraTiered AttributionTsanType AnnotationsValhallaVeronaVisualVMWakefieldZeroZGC

        © 2024 Oracle Corporation and/or its affiliates
        Terms of Use
        ·
        
            License: GPLv2
        · Privacy
        · Trademarks
