JDK Sandbox Development Repository

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 see 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 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.

Previous JDK 9 Sandbox Development Guidelines can be found here.

*** Never push changes to the default branch in the sandbox ***


FAQ

  1. Why should I not push to the default branch?
  2. What upstream repository is the sandbox sync'ed with?
  3. How are changes propagated from the main-line?
  4. What should I call my branch?
  5. Create a new branch
  6. Clone and update to a branch
  7. Pull and update to a branch
  8. Push a change to a branch
  9. Update a branch with the latest main-line changes
  10. Show all the changesets for a given branch
  11. Create a webrev for all changes in a given branch
  12. Close a branch

1. Why should I not push to the default branch?

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
    
6. Clone and update to a 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
    
7. Pull and update to a branch

        # pull latest changes
        cd sandbox
        hg pull

        # Update to the branch.
        hg update -r JDK-8000000-branch
    
8. Push a change to a 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
    
9. Update a branch with the latest main-line changes

        # 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
    
10. Show all the changesets for a given branch

        # pull latest changes
        cd sandbox
        hg pull

        # show all the branches changesets
        hg log -b JDK-8000000-branch
    
11. Create a webrev for all changes in a given 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
    
12. Close a branch

        # 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