Openj9: HOWTO Request: Managing changes across dependent repos

[mgaudet]

Like all projects, OpenJ9 builds on the shoulders of Giants. As a potential contributor, one of my concerns is understanding how I make a contribution to OpenJ9 that might span OpenJ9, OMR, an/or the OpenJDK extensions

[pshipton]

Please clearly state and link to the co-dependencies in the pull requests so the committers can coordinate merging the changes. Obviously they all need to be reviewed and approved before any are merged.

The automation is not yet in place to mirror from https://github.com/eclipse/omr/ to https://github.com/eclipse/openj9-omr/ so it's currently a manual process to bring OMR updates to OpenJ9.

[DanHeidinga]

The openj9-omr mirror exists for a couple of reasons: one of the primary ones being to allow tagging the OMR level and OpenJ9 level consistently.

The goal is always to make changes in the upstream project (Eclipse OMR / OpenJDK) if they are outside the core OpenJ9 code base and consume them into OpenJ9 from there.

[mgaudet]

So, is there any documentation about all these repos and how they tie together?

[mstoodle]

We're working on that. Here are some basics, hopefully this helps at least a bit :

The Extensions for OpenJDK for OpenJ9 repository (https://github.com/ibmruntimes/openj9-openjdk-jdk9) is a git mirror of the OpenJDK hg forest but does not include the HotSpot JVM (that's the master branch). The goal is for that master branch to bring OpenJDK commits across as they happen. The "openj9" branch in this repository adds a set of patches to the OpenJDK files to allow Eclipse OpenJ9 to integrate as the JVM. IBM has chosen, for the moment, to maintain this code themselves without accepting external contributions. That's a work in progress and we are very much intending to contribute that code to OpenJDK (hopefully as soon as possible) so that we can open up the access to those code changes.

When you follow our build instructions, you clone this "Extensions" repository, checkout the openj9 branch, and then build it the same way you would build OpenJDK. When you run bash get_source.sh, it will fetch two additional repositories specific to Eclipse OpenJ9: https://github.com/eclipse/openj9 , and an OpenJ9 mirror of the Eclipse OMR project https://github.com/eclipse/openj9-omr .

The Eclipse OpenJ9 repository is a JVM. It is built using the technology components (platform porting library, garbage collection, just in time compiler) from the Eclipse OMR project.

To facilitate working with the Eclipse OMR code base, Eclipse OpenJ9 maintains its own mirror of Eclipse OMR (that's the openj9-omr repository) along with an "openj9" branch which we can use for a couple of purposes. One @DanHeidinga outlined in his response above (to track changes happening in Eclipse OMR to see if anything breaks OpenJ9). Another is so that we have a place where we can make coordinated changes (dependent changes between OpenJ9 and OMR) without using the full turnaround time through the Eclipse OMR project. As Dan says, though, our goal is always to upstream to Eclipse OMR as much as possible, because it's more efficient to maintain the code upstream.

Not all of these "flows" have been automated yet. We should really have issues opened so people can track that work @AdamBrousseau @charliegracie

[mgaudet]

To clarify: Is the expectation going to be that contributors delivering a dependent change will open their own PR against openj9-omr on the openj9 branch? Or will committers take care of that, based on their judgement?

[mstoodle]

Preferably, contributors will submit to Eclipse OMR directly and those will "reach" the OpenJ9 project via what will eventually be a mostly automated flow into the "openj9" branch of openj9-omr.

If there's a need to deliver something more quickly or you can convince us that there's a really good reason to do the change first in Eclipse OpenJ9, then we'll consider a PR filed against the openj9 branch of openj9-omr.

[JamesKingdon]

Mark's summary above looks like a candidate for the sort of short pieces of info that might work well in the wiki (#1565). Or did we already document this elsewhere?