Page History

The JDK 9 project is experimenting with the idea of submission forests.  A submission forest submit repo allows committers to submit a change for automatic build , test and integration with an upstream forest.  Initially we plan a jdk9/hs-submit forest which will integrate to jdk9/hs.  This will allow and test. This allows 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 will still apply.

A test version of the Hotspot submission forest exists today.  The submission forest is jdk9/hs-demo-submit and its upstream forest is jdk9/hs-demo, a throw-away clone of jdk9/hs.  Currently, push access to hs-demo-submit is restricted to a few beta testers.

Basic Operation

test on the platforms supported by Oracle. 

Basic Operation

The submit repo is modeled after JDK sandbox repoSubmission forests are modeled after the JDK 9 sandbox forest.  The default branch of the submission forest submit repo is automatically sync'd with its upstream forest.  Committers do their work on named branches with one branch used per fix.  When repo. When a branch is pushed to the submission forestupdated in the submit repo, it is automatically run through a predefined 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  Once the build and test is done, a status email is sent to the committer.

A Simple Example

The example below, uses the defpath.py Mercurial extension.  This extension is available from the Code Tools project.

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 tcloneclone --branch default http://hg.openjdk.java.net/jdk9jdk/hs-submit
$ hg -Rcd hs-submit
$ hg tdefpathdefpath -du <OpenJDK id>
$ 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

A Note on the Examples

...

FAQ

What should I call my branch?

We recommend you Only branches starting with “JDK-“ will be built and tested, name your branch with the bug JBS id of your fix/enhancement.  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?

Branches without code changes will not be picked up and builtThe 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 forestsubmit repo, you should merge in the latest upstream changes onto your branch.

$ # From local forest
$ hg tpullpull # 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 merge default 
$ hg tcommit

...

commit

...

If you'd like to avoid this oddity, you may prefer to rebase your change like this:

$ # 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 -R hotspot rebase -d default --keepbranches
$ hg -R jdk rebase -d default --keepbranches

Unfortunately the trees extension does not support a trebase command.  Note that the rebase extension may need to be enabled in your .hgrc file prior to using the rebase command.

How should I push a branch?

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

$ hg tpushpush --new-branch

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

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

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

What happens when I push my changes?

When changes are pushed to a branch in a submission forestthe submit repo, 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 quicklyA job usually takes a couple of hours to complete.  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 yourselfthere are failures reported in the email, contact an Oracle engineer and provide her with the token ID/URL 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

...

submit repo?

Changes from the default branch of the upstream forest are JDK repo is pulled into the submission forest submit repo automatically. 

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?

When a change to branch B is pushed to the submission forest, the difference between the head of B and the latest common ancestor of B and the default branch is computed as a single patch.  This patch is then applied to the default branch in a child of the upstream forest.  The commit message for the patch is taken from the commit message at the head of branch B.  If the patch applies cleanly without jcheck errors and without needing manual merging, the child of the upstream forest is built & tested.  If all builds and tests succeed, the child of the upstream forest is pushed into the upstream forest and the job is complete.

Should I close my branch?

Should I close my branch?

Once you no longer have any need for the branch, you should close it. Do 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.  Let's say you have branch "JDK-7000001" in the jdk repository that needs to be closed.  You could do the following:

$ # From the root of your local forest
$ hg -R jdk update -C "JDK-7000001"
$ hg -R jdk commit --close-branch -m "AbandoningClosing changes.branch"
$ # Update repo to another branch to avoid mistakenly re-opening the closed branch.
$ hg -R jdk update default 

...

Can I reuse a branch for a different fix?

...

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 tloglog --branch "JDK-4040458"

How do I report problems?

If you have problems with submission forestssubmit repo, please send mail to  ops@openjdk.java.net