The primary purpose of the JDK 9 Sandbox Development Forest is to facilitate OpenJDK developers that are working on non-trivial changes, possibly JEP-scale effort, whose scope and duration make it necessary to collaborate with others in an open shared version control system, rather than just using privately shared patches.
Working in the sandbox can facilitate rapid iterative development, as there is no requirement for changes to be reviewed or accompanied by bug numbers, i.e. jcheck is not enabled. Just create a new branch and start working. When the changes are ready for integration into the main-line, then they will need to follow the appropriate forest integration rules. Any committer to the JDK 9 project can push changes to the sandbox. The formal proposal to setup the sandbox can be see here.
This forest will be maintained by Chris Hegarty at oracle dot com. Questions or issues relating to it should be directed to the maintainer. It is strongly recommended that you subscribed to the changes mailing list if you are actively developing changes in the sandbox.
The remainder of the document will address common questions and guidance for using the sandbox.
Changes from the upstream main-line forest are pull down into the default branch in the sandbox. This is done automatically. Any changes pushed to a default branch in the sandbox will cause a conflict when the upstream main-line changes are pulled. The conflict could be trivially resolved, but from that point on all changes pulled from the main-line will need to be merged. This is burdensome for the maintainer, and difficult to determine if the merges are from "real" changes, or just the merging of heads. To keep maintenance simple, non upstream main-line changes are forbidden from the default branch.
2. What upstream forest is the sandbox sync'ed with? 3. How are changes propagated from the main-line?The main-line forest is checked periodically, and any changes are pulled down into the default branch in sandbox.
4. What should I call my branch?Branch names should contain the suffix '-branch', to clearly identify them from other metadata in the changeset.
Branch names JEP-XXX-branch and JDK-XXXXXXX-branch are, by courtesy, reserved for use of the corresponding JBS issues. Branch names prefixed with an OpenJDK username and a delimiter, by courtesy, are reserved for use of that OpenJDK user.
5. Create a new branch
# clone the sandbox forest root repository
hg clone http://hg.openjdk.java.net/jdk9/sandbox sandbox
# get the rest of the forest
cd sandbox
sh get_source.sh [optional closed repo uri]
# set the default push path
sh common/bin/hgforest.sh defpath -du <OpenJDK Id>
# Create your branch in all repos
sh common/bin/hgforest.sh branch JDK-8000000-branch
# A dummy changeset to mark that you branched (reduces confusion later)
sh common/bin/hgforest.sh commit -m "Initial changes for JDK-8000000"
# Push the dummy changesets, requires explicit option to acknowledge new branch creation
sh common/bin/hgforest.sh push -b JDK-8000000-branch --new-branch
# clone the sandbox forest root repository
hg clone http://hg.openjdk.java.net/jdk9/sandbox sandbox
# get the rest of the forest
cd sandbox
sh get_source.sh [optional closed repo uri]
# set the default push path
sh common/bin/hgforest.sh defpath -du <OpenJDK Id>
# Update to the branch.
sh common/bin/hgforest.sh update -r JDK-8000000-branch
# pull latest changes
cd sandbox
sh common/bin/hgforest.sh pull
# Update to the branch.
sh common/bin/hgforest.sh update -r JDK-8000000-branch
# pull latest changes
cd sandbox
sh common/bin/hgforest.sh pull
# Update to the branch.
sh common/bin/hgforest.sh update -r JDK-8000000-branch
# Verify that you are on the correct branch
hg branch
# Create the changeset(s)
sh common/bin/hgforest.sh commit -m "JDK-8000000-branch: Fix NPE"
# Verify and Push the changeset(s)
sh common/bin/hgforest.sh out -b JDK-8000000-branch
sh common/bin/hgforest.sh push -b JDK-8000000-branch
# pull latest changes
cd sandbox
sh common/bin/hgforest.sh pull
# make sure you are on the branch
sh common/bin/hgforest.sh update -r JDK-8000000-branch
# merge your branch with the default branch.
sh common/bin/hgforest.sh merge -r default # fails harmlessly if nothing changed
sh common/bin/hgforest.sh commit -m Merge # fails harmlessly if nothing changed
# push the reparented branch back.
sh common/bin/hgforest.sh push -b JDK-8000000-branch
# pull latest changes
cd sandbox
sh common/bin/hgforest.sh pull
# show all the branches changesets
sh common/bin/hgforest.sh log -b JDK-8000000-branch
# pull latest changes
cd sandbox
sh common/bin/hgforest.sh pull
# Note: for simplicity we will deal with a single repository,
# but the process can be repeated for additional repositories
# as needed.
#
# Identify the latest changeset merged into the branch from the main-line.
# The easiest way to do this is to sync in the latest
# changes, then the changeset can be referred to as 'default' (as it
# will be the latest changeset in the default branch).
# update to the default branch
hg update default
# revert the files in the working directory to the state in the branch
hg revert -r JDK-8000000-branch --all
# check that status reports the correct files
hg status
# create the webrev
webrev -o 8000000/webrev.XX -r default -u <userId> -c 8000000
# restore the state of files to that of the default branch
hg revert --all
# pull latest changes
cd sandbox
sh common/bin/hgforest.sh pull
# make sure you are on the branch
sh common/bin/hgforest.sh update -r JDK-8000000-branch
# close the branch
sh common/bin/hgforest.sh commit --close-branch -m 'Close JDK-8000000-branch'
sh common/bin/hgforest.sh push -b JDK-8000000-branch
# switch to the default branch so as not to inadvertently reopen the branch
sh common/bin/hgforest.sh update -r default