Merging upstream changes

The Lilliput main repository is maintained in a way such that the Lilliput-specific changes are always 'on top' of the JDK mainline changes. For example, at the time of writing, we maintain 4 changes, and it looks like this (O are random upstream changes, A..D are the Lilliput changes:

O--O--O--A--B--C--D

When merging from upstream, we get more changes on the mainline branch:

O--O--O--A--B--C--D
       \-O--O--O--O

And we merge them with the Lilliput changes, such that we replace them with the upstream changes (-s ours option of the git merge command). The result looks like this (M is the merge changeset):

O--O--O--A--B--C--D--M
       \-O--O--O--O-/

At this point, the state of the working directory would be 100% identical to the upstream that we just merge. Now we only need to transplant the Lilliput changes to the top again. I call them A'..D' to indicate that those changes are not exactly the same as A..D, the new changeset might require adjustments, sometimes even significant reworks, in order to deal with new upstream changes.

O--O--O--A--B--C--D--M--A'--B'--C'--D'
       \-O--O--O--O-/

The exact procedure for merging looks like follows:

# Make sure you are on the latest lilliput master branch
git fetch lilliput-main master
git checkout master
git merge lilliput-main master

# Fetch upstream jdk changes
git fetch jdk-upstream

# Create a branch that we are going to use to merge the upstream tag jdk-26+26.
# Notice that we create the branch from the jdk-26+26 tag - this will *not* have
# any Lillput changes.
git checkout -b merge-jdk-26+26 jdk-26+26

# Now we merge in the Lilliput master branch into our working branch,
# but we pick 'ours' for any changes, which means that the end result
# will still look exactly like jdk-26+26 with no Lilliput changes.
git merge -s ours master

# And now we transplant the Lilliput-changes one-by-one.
# First, look up the changeset ID of the first changeset
# (i.e. 'A' in our example above) in the git log or the GitHub web.
# Then we start the cherry-pick of that changeset:
git cherry-pick 80f9b900c21d633cd1c22071d3baea531e5c554a

# If there are no conflicts, then all is good and we can proceed to the
# next step. However, if there are conflicts, then you need to fix them,
# build and test the fixes, and finish the cherry-pick:
git cherry-pick --continue

# Even if there are no conflicts, I strongly recommend to build and
# test the changes before proceeding. I would recommend to run tier1 test
# with and without TEST_VM_OPTS="-XX:+UseCompactObjectHeaders".

# Now we are ready to cherry-pick the next changeset, look up the
# changeset ID of the next change (e.g. 'B' in the example), and
# repeat the above steps until all changes have been transplanted successfully.

# We often accumulate a number of fixes on top of the primary big changesets.
# It is useful to combine the fix changesets into their corresponding big
# changesets at this point. This can be achieved by using git rebase -i, and
# then squashing the fix changesets into their corresponding primary changeset.

# When all is done and tested, push the resulting branch to your personal repository
# and create a PR. The PR must have a title of the form:
#
# Merge jdk:jdk-26+26
#
# specifically the format is:
#
# Merge $UPSTREAM_PROJECT:$UPSTREAM_TAG
#
# When the title is correctly formatted like this, Skara will recognize the PR
# as a merge, which means that no formal review will be required and the changesets
# will not be squashed together when intergrated.
#
# Wait until GHA are done, if you are unsure about particular changes that you
# needed to make, then consider requesting a review for those changes, if feasible.
# Finally, enter /integrate into the PR to integrate the merge into the Lilliput main repo.

Page tree

Merging upstream changes