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 the 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 should I push a branch?

What's happening with my submission?

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

Why should I not push to the default branch?

Changes from the upstream forest are pulled into the submission forest automatically. You can keep your work on a fix branch in sync with what's going on upstream by simply merging in changes from the default branch.

Is jcheck turned on?

Jcheck 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 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 is my branch merged with the upstream forest?

How are changes from upstream brought into the submission forest?

How can I create a webrev for my branch?

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.

FAQ