General Instructions For Small Changes

Version 1

    Events

    You can work on small changes and bug fixes at any time. However, there are two important reasons why you will want to join the global series of events:

    1. It stops the official OpenJDK reviewers from being overwhelmed.
    2. You'll get lots of assistance on the day
    3. Your patch has more chance of being accepted
      1. We'll pre-review the patch for you and provide feedback
      2. We'll co-ordinate with the OpenJDK committers so they can review and commit patches

    Event Dates

    Patch Review Dates

    Apart from ad-hoc reviews, we're going to try and meet fortnightly on Sundays at 1400 BST on the #adoptopenjdk IRC channel (irc.freenode.net). The dates starting off are:

    • 24th of June
    • 8th of July
    • 22nd of July
    • TBA

    Project Sponsors

    There should be project sponsors for each effort, please see the individual sub project pages for their project sponsors.

    Instructions for instructors

    1. If you have not done so already, build the Adopt OpenJDK VM
      1. Alternatively you can ask attendees to build their own environment.
    2. Join the adoptopenjdk IRC channel on irc.freenode.net
      1. You can also ask questions on the official openjdk IRC channel (openjdk on irc.oftc.net)
    3. Join the Adopt OpenJDK group for discussions.
      1. You can also have discussions on the appropriate OpenJDK Mailing List.
    4. In order to submit patches you'll want to join the Patch Review GitHub project

     

    What fixes are accepted (The barrier for patches)

    The barrier for the OpenJDK committers to accept a patch (even one as seemingly simple as a warning clean-up) is exceptionally high. The instructors will be checking a wide variety of conditions before your patch can be accepted. Please survey the list for the specific sub project and try to ensure your patch meets the quality bar.

    Hardware Requirements

    Underpowered machines simply won't cut it when building the OpenJDK in the VM that's provided for this program. Those with a modern processor, 4GB+ RAM and a fast hard disk (e.g. SSD) will find that they can build the OpenJDK just fine. Others may struggle!

    Attendee Instructions

    Setting up your environment

    You can use one of two options:

    Re-run Auto Configure

    Every time you go back to doing OpenJDK work, you must ensure the build environment is up to date, in order to do so, run the following:

     cd $SOURCE_CODE ; cd jdk8_tl/common/makefiles ; bash ../autoconf/configure ; 

    Make changes

    See your individual sub project for instructions at this point.

    Run jtreg tests

    NOTE $SOURCE_CODE is where you installed the source code to. If you are using the Pre packaged VM then this is /home/openjdk/sources

    Using runJtregTests.sh

    Execute the following:

     cd $SOURCE_CODE cd jdk8_tl/jdk/test ./runJtregTests.sh <name of area to test> 

    For example ./runJtregTests.sh jdk_util

    NOTE: In order to figure out what package you need, you can run ./runJtregTests.sh with no arguments to get a complete listing.

    Manually

    See jtreg project and jtreg wiki for details on running jtreg tests. Generally speaking you'll want to run individual tests (i.e. Against the classes you've fixed) or tests based on a package, e.g. jdk_util

    NOTE $SOURCE_CODE is where you installed the source code to. If you are using the Pre packaged VM then this is /home/openjdk/sources

    Execute the following:

     cd $SOURCE_CODE cd jdk8_tl/jdk/test make "name of package you are testing" &> test.log ; 

    For example make jdk_util &> test.log

    Then check the test.log file for any test errors or failures

    NOTE: In order to figure out what package you need, you can look inside the MakeFile script itself, which gives you the list of valid packages.

    Repeat the Process

    See your individual sub project for instructions at this point.

    Create Patches

    Using createPatches.sh script

    NOTE: For now, this is the preferred mechanism for creating patches

    For each class that you've changed:

     cd $SOURCE_CODE cd jdk8_tl/jdk ./createPatches.sh 

    Individual Manual Patches

    For each class that you've changed:

     cd $SOURCE_CODE cd jdk8_tl/jdk hg diff /path/to/changed class.java <name of changed class>.patch 

    e.g. hg diff src/share/classes/com/oracle/net/Sdp.java > Sdp.patch

    Using Webrev

    NOTE: Please do not use this mechanism unless you're an experienced contributor and are sending patches directly to the OpenJDK project

    You can use the official webrev tool to create patches, in order to run webrev, execute the following:

     cd $SOURCE_CODE cd jdk8_tl/jdk hg commit -u <your OpenJDK username> -m "<sensible commit message>" ksh ../make/scripts/webrev.ksh 

    You'll then need to host the webrev somewhere for others to look at.

    webrev and forest.py

    You can ignore this if you don't know what forest.py is in context of OpenJDK. Some users maybe using the forest.py extension to create uber webrevs - sadly the latest version of Mercurial breaks this method - see http://robilad.livejournal.com/125607.html for details on how to downgrade your Mercurial for Mac OS X.

    Submit Patches

    There are a couple of ways you can submit patches:

    Using Github

    1. Join the Github project
    2. Create a fork
    3. Put your patches into the 1-unreviewed folder using the appropriate directory structure
      1. The dirctory structure is usually as follows:

    Category of BugFix core subpackages matching openjdk layout client subpackages matching openjdk layout

    For example, when submitting a javac warning bug fix for the Collections class, you'd submit it as:

     javac_warnings core java util Collections.java/patch 

    If the patch is non-trivial or you are unsure of its potential negative impact, please flag this in the Pull Request!

    1. Submit a Pull Request
      1. If the patch is non-trivial or you are unsure of its potential negative impact, please flag this in the Pull Request!
      2. Please make sure your email address, full name and java.net username (if you have one) is sent with that Pull Request so that you can be listed as having contributed!

    Mailing list

    1. Send the patch into Adopt OpenJDK group.
      1. You may wish to bundle your patches into one email
      2. If the patch is non-trivial or you are unsure of its potential negative impact, please flag this in the email!
      3. Please make sure your email address, full name and java.net username (if you have one) is sent with that patch so that you can be listed as having contributed!

    Directly to OpenJDK

    If you're an experienced contributor, then submitting the webrev directly to the appropriate OpenJDK project is fine.