Submission Forests

The JDK 9 project is experimenting with the idea of submission forests. A submission forest allows committers to submit a change for automatic build, test and integration with an upstream forest. Initially we have created a jdk9/hs-submit forest which integrates to jdk9/hs. This will allow non-Oracle committers to make changes to jdk9/hs directly while still observing the Hotspot team's conventions for pre-integration build & test. Of course all the usual rules about who may make changes and how they are reviewed and approved still apply.

Submission forests are modeled after the JDK9 sandbox forest. The default branch of the submission forest is kept in sync with its upstream forest. Committers do their work on branches with one branch used per fix. When a branch is pushed to the submission forest, it is automatically run through a pre-defined set of builds and tests. If this succeeds, the changes on the branch are moved as a single changeset to the default branch of the upstream forest. If a branch fails to build, pass tests or merge successfully into the upstream forest, no changes are made upstream. At the end of the process a status email is sent to the committer.

The finer points of submission forests are covered in the FAQ below. The jdk9/hs-submit forest will be maintained by <Duke>. If you have problems, please send mail to <hs-xxx@openjdk.java.net>

FAQ

A simple example

Say you need to make a simple fix to the hotspot README file in order to fix bug JDK-7000001. The following would do it:

$ hg tclone --branch default http://hg.openjdk.java.net/jdk9/hs-submit
$ cd hs-submit/hotspot
$ hg branch "JDK-7000001"
$ echo "Make the README longer." >> README
$ hg commit
$ # Get your code review here
$ hg push --new-branch

What should I call my branch?

We recommend you name your branch with the bug id of your fix. Since Mercurial branch names can't begin with a number, use the full bug id, like "JDK-4040458"

How should I create a branch?

Create a branch in each repository that you need to change. For example, if your fix requires changes in both the jdk and hotspot repos, you could do this:

$ # From the root of your local forest
$ hg -R hotspot branch "JDK-7000001"
$ hg -R jdk branch "JDK-7000001"

You can commit the empty branches immediately after they're created or wait until you have made code changes. Unlike the recommendation for the OpenJDK sandbox forest, you should not commit an empty branch in a repository that will not eventually have code changes. This will cause your fix to fail when it is merged with the upstream forest. This restriction will be removed in the future.

How do I supply a commit message for my change?

The commit message for the changeset at the head of your branch is used as the commit message for the changeset that is integrated to the default branch of the upstream forest.

How do I update my branch with the latest upstream changes?

Before you push a branch to the submission forest, you should merge in the latest upstream changes onto your branch.

$ # From local forest
$ hg tpull # make sure the default branch has latest changes
$ hg -R hotspot update "JDK-7000001"  # make sure you are sitting on your branch
$ hg -R jdk update "JDK-7000001"
$ hg tmerge default #tmerge
$ hg tcommit -m "Merge"#tcommit

How should I push a branch?

The first time you push a new branch to the submission forest, you need to use the "--new-branch" option like this:

$ hg tpush --new-branch

Subsequent pushes to your branch in the submission forest do not need the "--new-branch" option.

If your local forest has several fixes under development and you're ready to push only one, you can do that with the "--branch" option:

$ hg tpush --branch "JDK-4040458" --new-branch

What happens when I push my changes?

When changes are pushed to a branch in a submission forest, a job is created on an internal Oracle system to build and test those changes. Jobs which integrate to the same upstream forest are run sequentially in order to manage merge issues so it is possible that your job will wait for some time to get started. Once running, a successful job should take about <60> minutes to complete. Unsuccessful jobs will usually complete more quickly. When your job is finished you will get an email describing what happened. If you are subscribed to the change alias for the upstream forest, you should also see an email if your change successfully integrates upstream.

What if my submission fails?

Your submission may fail to integrate with the upstream forest for several reasons:

it may fail to build on one or more platforms
it may fail tests on one or more platforms
it may not merge cleanly with the default branch of the upstream forest

You will get an email describing which of these things happened; however, these emails are brief. At this time we are not able to provide build or test logs which fully describe the problem. If you are unable to diagnose the problem yourself, contact an Oracle engineer and provide her with the token in your email message. She will be able to access internal logs and help you resolve the problem.

Once the problem is found, you may make further commits to your branch and push again to the submission forest. Remember that the commit message from the head of your branch will be the one that is eventually used when your change is merged upstream.

How are changes from upstream brought into the submission forest?

Changes from the default branch of the upstream forest are pulled into the submission forest automatically every few minutes.

Can I work on the default branch?

You can not make changes directly on the default branch of the submission forest. Your changes will appear on the default branch of the submission forest after they have been integrated upstream then automatically pulled down. Adding your changes directly to the default branch could require merges when the default branch is updated automatically and would likely break the automation. For this reason, changes to the default branch of the submission forest are disabled.

Is jcheck turned on?

The jcheck Mercurial extension is not enabled for the submission forest; however, it generally is enabled for the upstream forest. If so, your change must pass jcheck when it is merged with the upstream forest.

How is my branch merged with the upstream forest?

Should I close my branch?

Once your branch has been integrated upstream, it will be closed automatically. This is the common case. Occasionally though, there may be a branch that needs to be abandoned. This might happen when a branch has been pushed to the submission forest but failed to integrate upstream.

Can I reuse a branch for a different fix?

Branches are intended to be used for a single fix. They are automatically closed once the branch is integrated upstream and should not be reopened.

How can I show all changes for my branch?

To see all the changes for a branch named "JDK-4040458" you can do this:

$ hg tlog --branch "JDK-4040458"