The primary purpose of the JDK Sandbox Development Repository 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 project integration rules. Any committer to the JDK project can push changes to the sandbox. The formal proposal to setup the sandbox can be seen here.
This repository will be maintained by Chris Hegarty at oracle dot com. Questions or issues relating to it should be directed to the maintainer. It is recommended that you subscribe 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.
Previous JDK 9 Sandbox Development Guidelines can be found here.
Changes from the upstream main-line repository 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.
If changes are accidentally pushed to the default branch, please contact the sandbox maintainer so that the problems they cause can be resolved.
2. What upstream repository is the sandbox sync'ed with?http://hg.openjdk.java.net/jdk/jdk
3. How are changes propagated from the main-line?The main-line repository 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 repository root repository
hg clone http://hg.openjdk.java.net/jdk/sandbox sandbox
cd sandbox
# set the default push path
hg defpath -du <OpenJDK Id>
# Create your branch
hg branch JDK-8000000-branch
# A dummy changeset to mark that you branched (reduces confusion later)
hg commit -m "Initial changes for JDK-8000000"
# Push the dummy changesets, requires explicit option to acknowledge new branch creation
hg push -b JDK-8000000-branch --new-branch
# clone the sandbox repository root repository
hg clone http://hg.openjdk.java.net/jdk/sandbox sandbox
cd sandbox
hg defpath -du <OpenJDK Id>
# Update to the branch.
hg update -r JDK-8000000-branch
or
# clone the just the specific branch
hg clone -b -r JDK-8000000-branch http://hg.openjdk.java.net/jdk/sandbox sandbox
# pull latest changes
cd sandbox
hg pull
# Update to the branch.
hg update -r JDK-8000000-branch
# pull latest changes
cd sandbox
hg pull
# Update to the branch.
hg update -r JDK-8000000-branch
# Verify that you are on the correct branch
hg branch
# Create the changeset
hg commit -m "JDK-8000000-branch: Fix NPE"
# Verify and Push the changeset(s)
hg out -b JDK-8000000-branch
hg push -b JDK-8000000-branch
# pull latest changes
cd sandbox
hg pull
# make sure you are on the branch
hg update -r JDK-8000000-branch
# merge your branch with the default branch.
hg merge -r default # fails harmlessly if nothing changed
hg commit -m Merge # fails harmlessly if nothing changed
# push the re-parented branch back.
hg push -b JDK-8000000-branch
# pull latest changes
cd sandbox
hg pull
# show all the branches changesets
hg log -b JDK-8000000-branch
# pull latest changes
cd sandbox
hg pull
# 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
hg pull
# make sure you are on the branch
hg update -r JDK-8000000-branch
# close the branch
hg commit --close-branch -m 'Close JDK-8000000-branch'
hg push -b JDK-8000000-branch
# switch to the default branch so as not to inadvertently reopen the branch
hg update -r default