Eclipse OpenJ9 Release Process

The OpenJ9 JVM is composed of two code repositories:

• OpenJ9 https://github.com/eclipse-openj9/openj9

• OMR https://github.com/eclipse-openj9/openj9-omr

and one has an external test repo:

• https://github.com/eclipse-openj9/openj9-systemtest

OpenJ9 needs to be combined with code from OpenJDK to create a Java SDK. The OpenJDK code is managed in separate github repos referred to as the "Extensions for OpenJDKx for OpenJ9". There are multiple extensions repos:

• JDK8 https://github.com/ibmruntimes/openj9-openjdk-jdk8

• JDK11 https://github.com/ibmruntimes/openj9-openjdk-jdk11

• JDK17 https://github.com/ibmruntimes/openj9-openjdk-jdk17

• etc.

• JDK.next https://github.com/ibmruntimes/openj9-openjdk-jdk

An OpenJ9 release should:

• Use a single code base to support the various JDK-levels.

• Track the upstream OpenJDK releases.

• Use a consistent set of tags across OpenJ9 & extensions repos to ensure that releases can be rebuilt or branched later.

• OpenJ9 releases should be high quality and pass a common quality bar.

• Communicate the tags for a release to downstream projects.

• Clearly define the supported platforms

• Should not regress performance from release to release.

• Use Github releases to identify releases and link to the relevant data.

• Should tag the openj9-systemtest repo as well so the systemtest level used to validate a build is known.

Release cadence

OpenJ9 should aim to release quarterly to match the OpenJDK long term support (LTS) release cadence. OpenJDK 8, 11, 17 are released quarterly and other LTS releases will likely follow similar release cadences. There should be milestone builds created as the project advances towards the next release.

OpenJ9 will endeavour to finalize a source code release within two weeks of the corresponding OpenJDK release. When the project determines this deadline cannot be met, a new estimate will be publicly announced after analysis of the issues blocking the release. This is not meant to be an exact date but to provide a new maximum, such as "provide a source code release within the next two months".

Quality bar

Work with the Adoptium community to define a common quality bar for any OpenJDK-based JDK. The aim is to define a set of tests, both functional and stress, and 3rd party applications that should pass for every release.

Platform support

Define the platforms that are supported by a release. The set of platforms will depend on the availability of hardware at OpenJ9, Adoptium and IBM that can be used to validate the platform meets the quality bar. The code base may support more platforms than can be validated by the quality bar. Such platforms will not be officially included in the release.

Performance

OpenJ9 should avoid regressing performance from release to release. Each release should document the set of benchmarks and performance measures that will be tracked for the release. These measures should include the acceptable noise margins that will be used when tracking the measure. Regressions may be unavoidable at times due to changes required to be compliant with the Java specifications, to close security holes, or to address the need to update / modify the architecture. Some regressions may simply be found too late in a release to address them. The project may decide to trade performance - whether throughput, startup or fooprint - for another important measure. Any regressions should be documented as part of the release plan.

Note, detecting regressions will be difficult in the open project given the limited hardware resources available. Work is being done at Adoptium to enable performance testing.

Release Process

1. Create an issue to track the release and record the information required above, including the SHAs and tags. This information will mostly be duplicated with the Eclipse release plan.

2. Pick a candidate OpenJ9 level to mark as the initial release candidate. This should be a level that has successfully passed the nightly testing builds at both OpenJ9 and IBM. Given these builds may target a range of SHAs, a candidate SHA should be taken from within that range.

3. Branch the openj9 & openj9-omr repos at the specified level. Branch names should be of the form: v#releaseNumber#-release. Immediately tag the newly created branch with a tag of the following form: openj9-#releaseNumber#-m#milestonenumber#. For the 0.8.0 release, this would result in a v0.8.0-release branch with a openj9-0.8.0-m1 tag. These branches are not intended as development branches and no continued support will be done on them. They are merely points in time.

4. The Extensions repos should have been branched for each of the releases. Update the Extensions branches to pull the tagged levels from the openj9 & openj9-omr release branches.

5. Rebuild the tagged levels and ensure they pass the quality bar defined by Adoptium. These builds need to have extra configure options which will identify them as release builds. These options are--with-milestone=fcs (JDK8 - don't use the default option for an internal build) or --without-version-pre --without-version-opt (JDK9+ - don't set pre-release identifier or OPT field that contains a timestamp) added to the ./configure command line. These ensure that the correct version string is displayed in the java -version output.

6. Provide a window of time (multiple weeks) for any stakeholders to highlight any stopship issues with the milestone build. If any are found, a determination can be made to either:

   • Apply a targeted fix to the release branch and re-tag, or

   • Rebase the release branch on the master branch if the changes that have gone in between the initial milestone tag and now are safe.

7. Retag the -mX level as openj9-#releaseNumber#. For the 0.8.0 release this will be openj9-0.8.0.

8. Create the github release corresponding to the tagged level. The release should link to the Eclipse Release document, and the release issue.

9. Open an Eclipse Bugzilla requesting the branch be marked protected to prevent commits after the release is complete.

10. Remove the doc:releasenote tag from items that were included in the release notes.

For milestone builds, the tag will be of the form: openj9-0.8.0-m1.

Note, use annotated tags (git tag -a <tag name>) as they are treated specially by git compared to simple tags.

The java -version should now show the tagged level due to the ${java.vm.version} property being set to the tag. Javacores will also display the tag if the build has been tagged.