How to contribute

This page describes the sponsored-contribution process for the JDK 7 and JDK 8 Projects. Other Projects may follow these conventions or may establish their own; please consult the appropriate Project pages for details.

This process is intended for developers who already have the skills required to work on the JDK but who do not yet have full authorship (i.e., committer) rights. It allows such developers to demonstrate their abilities by submitting meaningful contributions in the form of patches and by pairing them with sponsors, i.e., existing authors who can offer advice, help them become familiar with the JDK development process, and eventually push their patches into the appropriate Mercurial repository. Over time it's expected that skilled contributors will eventually earn full authorship rights for themselves.

This page focuses on the contributing side of the process; a companion page describes how to sponsor a contribution.

0. Become a contributor

Like many other open-source communities, the OpenJDK Community requires contributors to jointly assign their copyright on contributed code. If you haven't yet signed the Oracle Contributor Agreement (OCA) then please do so, scan it and e-mail the result to oracle-ca_us(at)oracle.com. Please make sure to specify your java.net user name, and to specify OpenJDK as the project you'd like to contribute to so that we can process and store your OCA.

The OCA gives Oracle and the contributor joint copyright interests in the code. The contributor retains copyrights while also granting those rights to Oracle as the Community's sponsor. You only need to sign the OCA once in order to cover all changes that you might contribute to any Oracle-sponsored open-source community including not just OpenJDK but also, for example, GlassFish, NetBeans, and MySQL. If you've already signed the OCA or the former SCA (Sun Contributor Agreement) for any Oracle-sponsored open-source community, then you do not need to sign it again in order to contribute to OpenJDK. (You can learn more about the OCA by consulting its FAQ.)

1. Find something interesting to work on

The most obvious thing to work on is a bug or enhancement (RFE) about which you are passionate. Please check the "Java" category of the online bug database to see if your idea is already described there, and if so then use that bug/RFE's id number when writing about your work. If there's no existing bug or RFE then that's fine too; we just ask that you use a relevant id for tracking purposes, if one exists.

If you're interested in a particular area but don't have any specific ideas about what to do then feel free to post a query to the appropriate Group or Project development list to ask for suggestions that match your skills and knowledge. A list of all the Groups and Projects may be found at the left-hand side of this page; you are more than welcome to subscribe to any of their mailing lists.

2. Discuss your intended change

Before you invest significant time working on a change it may be worth discussing what you're trying to do with other engineers working on the same code. They're likely to be able to offer comments and suggestions that will result in a higher-quality change and a smoother submission process. Announcing that you're working on a particular item can also help to avoid wasted effort in case someone else is already working on it.

If you're thinking of working on an existing bug or RFE that's already tracked in the Sun bug database then the best way to start such a discussion is to post a message to the appropriate development list with a subject line of the form

6543210: My favorite bug

where 6543210 is replaced with the actual Sun bug or RFE id number and My favorite bug is replaced with the bug or RFE's synopsis.

3. Submit a patch

When your change is ready, create a new bug report in the OpenJDK Bugzilla system. You'll have to register with that system first if you haven't already done so.

The description field of your bug report should contain the following:

• A summary of the problem that your patch solves or the need that it addresses;

• A description of the change, including a rationale for your approach and a discussion of any alternative approaches that were considered, if relevant; and

• If your patch is related to an existing Sun bug then add a string of the form sunbug=1234567 to your Bugzilla bug's whiteboard, replacing 1234567 with the actual seven-digit Sun bug id.

Use attachments to your bug report to convey the following:

• The code change itself, relative to an existing changeset in the appropriate Mercurial repository. The preferred form is generated by Mercurial's hg export command, with the -g option so that file renames are tracked correctly. The output of hg diff -g is also acceptable, and in the worst case traditional unified diffs (-u) are okay too, at least for simple changes.

• A unit test, written for the jtreg test harness, that validates your change. The test should fail when run against a build without the change and succeed when run against a build with the change. Unit tests aren't always practical, especially for changes such as performance improvements or fixes to bugs that are highly platform-dependent, but if practical then a unit test is required.

We use a flag in Bugzilla to identify contributions in need of a sponsor. Once you've completed your new bug report, set the sponsor flag to the request state, i.e., to "?".

4. Work with your sponsor

If an existing JDK 7 or JDK 8 author decides to sponsor your proposed change then that person will set the sponsor flag to the granted state, i.e., "+", and take ownership of your bug.

Your sponsor will evaluate your patch for correctness, compatibility, stability, performance, coding style, and overall appropriateness to the current phase of the intended Project's development. Your sponsor will work with you to address any remaining deficiencies and then guide you through the rest of the development process, navigating the relevant internal Oracle engineering processes on your behalf and ultimately, if all goes well, pushing your patch into the appropriate Mercurial repository.

5. Know what to expect

Only the best patches submitted will actually make it all the way into a JDK code base. The goal is not to take in the maximum number of contributions possible, but rather to accept only the highest-quality contributions. The JDK is used daily by millions of people and thousands of businesses, often in mission-critical applications, and so we can't afford to accept anything less than the very best.

If you're relatively new to the Java platform then we recommend that you gain more experience writing Java applications before you attempt to work on the JDK itself. The purpose of the sponsored-contribution process is to bring developers who already have the skills required to work on the JDK into the existing development community. The members of that community have neither the time nor the patience required to teach basic Java programming skills or platform implementation techniques. (Oracle offers formal training if that's what you're looking for.)

The feature release currently under development is JDK 8. Most development work is focused on that release, so generally you should be working against the latest JDK 8 sources rather than the JDK 7 sources. Fixes for critical bugs may eventually be backported from JDK 8 to JDK 7, but only after they "soak" in JDK 8 for at least one full test cycle (about six weeks).