How to contribute

This page describes the sponsored-contribution process for the JDK and JDK Updates 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 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 Committers for the Project 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 commit 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 OpenJDK as the project you'd like to contribute to so that we can process and store your OCA. Allow at least two weeks for processing. If your request is urgent contact the appropriate Project Lead.

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. Please note that you do not need to sign an OCA if you work at Oracle or a company which has negotiated an equivalent agreement. (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 "JDK" Project of the 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. A complete list of all of the Groups, Projects, people and their roles may be found in the census.

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 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 OpenJDK bug or RFE id number and My favorite bug is replaced with the bug or RFE's synopsis.

3. Submit a patch

Your patch must be built and tested on all relevant platforms before submission. Refer to the appropriate release-specific build and test instructions for JDK (build, test) or JDK Updates (build, test). If you have problems building, you may send your questions to the Build Group's mailing list. Note that a full build against recently synchronized sources with only your applied patch is required for each submitted change.

When your change is ready, send a message to the appropriate development list with a subject line of the form

[PATCH] 6543210: My favorite bug

where 6543210 and My favorite bug are replaced as above. If no existing bug or RFE describes your change then omit the id number and one will be created and assigned.

The message should contain three things, either directly, or in the body as attachments:

• A description of the change, including a rationale for your approach and a discussion of any alternative approaches that were considered, if relevant. If no existing bug or RFE describes your change then also include a description of the problem that it solves or the need that it addresses.

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

4. Work with your sponsor

If an existing JDK or JDK Updates Committer decides to sponsor your proposed change then that person will 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 releases currently under development are in the JDK Project. Most development work is focused on the newest release, so generally you should be working against the latest JDK sources rather than the JDK Updates sources. Fixes for critical bugs may eventually be backported, but only after they "soak" in JDK for at least one full test cycle (about six weeks).