How to contribute to the OpenJDK project
This page describes the contribution process for the OpenJDK project. This interim process will be used until an open governance model for the project is established.
The design of this process is based loosely upon the contribution process of the JDK 6 project. The most significant difference is that this new process is based upon open e-mail lists rather than web-based forums and forms. This change is motivated by the observation that most developers tend to prefer e-mail for ongoing technical conversations.
0. Become a contributor
Like many other open-source projects, the OpenJDK project requires contributors to jointly assign their copyright on contributed code. If you haven't yet signed the Sun Contributor Agreement (SCA) then please do so and fax it to +1-408-715-2540, or scan it and e-mail the result to sun_ca(at)sun.com.
The SCA gives Sun and the contributor joint copyright interests in the code. The contributor retains copyrights while also granting those rights to Sun as the project sponsor. You only need to sign the SCA once in order to cover all changes that you might contribute to any Sun-sponsored open-source project including not just the OpenJDK project but also, for example, GlassFish, NetBeans, and OpenSolaris. If you've already signed the SCA in order to contribute to some other Sun-sponsored project then you do not need to sign it again in order to contribute to the OpenJDK project. (You can learn more about the SCA 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 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 development list to ask for suggestions that match your skills and knowledge.
2. Discuss your intended change
Before you invest time working on a change, discuss 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 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 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, 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 in the body or 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
A Sun engineer whose knowledge and skills are a good match for your proposed change will be assigned as your sponsor and will reply to your message.
You can generally expect a reply within about five working days; actual response times will vary due to factors such as impending product-release deadlines, contribution volume, and holiday schedules. You should also expect a longer response time if you haven't already discussed your proposed change on the appropriate development list, since it will take more time for your sponsor to come up to speed on what you're trying to do.
Your sponsor will first evaluate your patch for correctness, compatibility, stability, performance, coding style, and overall appropriateness to the current phase of development. If your change passes inspection then your sponsor will work with you to address any minor deficiencies and then guide you through the rest of the development process, navigating the relevant internal Sun engineering processes on your behalf and ultimately, if all goes well, integrating your patch into the JDK.
5. Know what to expect
Only the best patches submitted will actually make it all the way into the JDK source base. Sun's goal is not to accept the maximum number of contributions possible, but rather to accept only high-quality contributions that improve the JDK.
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. Sun's aim here is to bring developers who already have the skills required to work on the JDK into the existing JDK 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. (Sun offers formal training if that's what you're looking for.)
The feature release currently under development is JDK 7. Almost all development work is focused on that release, so generally you should be working against the latest JDK 7 sources rather than the JDK 6 sources. Fixes for critical bugs may eventually be backported from JDK 7 to a JDK 6 update release, but only after they "soak" in JDK 7 for at least one full test cycle (about six weeks).
Builds of JDK 7 are, for now, only being promoted to testing and thence to the OpenJDK download area and source repository about twice a month. This means that once your patch is integrated it might not show up in the OpenJDK sources for two or three weeks. The frequency of promoted builds will increase as we get further into the JDK 7 development cycle.
