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.
Submission forests are modeled after the JDK 9 sandbox foresttest on the platforms supported by Oracle.
The submit repo is modeled after JDK sandbox repo. 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 $ hgcd -R hs-submit tdefpath$ hg defpath -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
Many of the examples on this page use the
defpath.py Mercurial extensions. These extensions are available from the Code Tools project. These extensions are not necessary for using submission forests but they make handling multi-repo forests easier. Other methods for handling multiple repos, such as the
common/bin/hgforest.sh script, work as well.
|Table of Contents|
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?
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.
Branches without code changes will not be picked up and built.
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
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 A job usually takes a couple of hours 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, there 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
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?
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 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?
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 tloglog --branch "JDK-4040458"
How do I report problems?
If you have problems with submission forestssubmit repo, please send mail to firstname.lastname@example.org