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-dev@openjdk.java.net>

Quick Start

Say you need to make a simple fix to the README file at the head of the hotspot repository. This fix addresses 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
%
% # Get code review here
%
% hg commit -l msg.txt
% hg push --new-branch

FAQ

How to get started

To get started, make a clone of the submission forest using your favorite method. In these examples we use the Mercurial trees extension. You may find it convenient to clone only the default branch.

% hg tclone --branch default http://hg.openjdk.java.net/jdk9/hs-submit

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?

\[ Should we recommend the empty changeset for every tree like they do in the sandbox forest? What happens to our automation if empty changesets are pushed?\]

How should I push a branch?

What if my submission fails?

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 used?

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 automatically be closed.

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.