How to Contribute Code to Mustang

By Graham Hamilton

April 2005

As part of the development process for the Mustang [ https://mustang.dev.java.net/ ] release of the Java 2 Platform, Standard Edition (J2SE 6.0), we are moving to a more transparent development model for both the specification and the implementation. The various Mustang specifications are all being developed through the Java Community Process (JCP) [ http://jcp.org/en/home/index ], with the overall umbrella JSR for Mustang at JSR 270 "J2SE 6.0 (Mustang) Release Contents" [ http://jcp.org/en/jsr/detail?id=270 ]. The JCP has recently made some process changes to encourage greater community access to specifications that are under development. As part of that effort, Sun will be providing frequent public updates of the JSR 270 specification whenever there are significant changes.

Now, while the specifications matter, so does the implementation. We've heard from developers that they would like:

Ability to download and read J2SE source code, for both final releases and for interim development builds.
Ability to fix bugs and deploy them internally.
Ability to contribute both bug fixes and features back into the mainline J2SE releases.

Along with these requests we also hear repeatedly that "Compatibility Matters!" Many developers demand strong cross-platform compatibility and they want that value to be retained and reinforced. We're sometimes scolded about gaps or holes in the cross-platform compatibility requirements (sorry!) but it is very rare for developers to tell us that compatibility requirements should be removed or weakened.

We've been attempting to address these different requests and this has resulted in us taking some significant steps to simplify source licensing, improve source code access, and encourage active contributions into J2SE.

Improved Source Licensing

We are developing three new source licenses targeted at specific uses:

The Java Research License (JRL) [ http://java.net/jrl.html ] for evaluation and non-commercial use.
The Java Distribution License (JDL) for full-scale commercial use.
The Java Internal Use License (JIUL) to allow bug-fixing and commercial deployment inside a company or organization.

Of these three licenses, the JRL is by far the most important for most developers, and is reasonably simple, as licenses go, although it took an amazing number of lawyers to create this simplicity. The JRL is a simple two page click-through license which allows you to read the J2SE source code and make experimental changes. And for developers that ask, "Does looking at source code under the JRL taint me?", the answer is "No!" See the JRL FAQ #18 [ http://java.net/jrl.html ] for more details.

Improved Source Access

We have released the complete J2SE 5.0 source code [ http://java.sun.com/j2se/jrl_download.html ] under the JRL. This includes the complete, buildable, J2SE 5.0 ("Tiger") sources. Tiger is the largest update to J2SE since JDK 1.0. It's a great release and if you are not already on Tiger, I would encourage you to move there as soon as you can!

While Tiger continues to move into widespread use, the J2SE engineering team has already shifted our focus on to creating the next major new release, J2SE 6.0 "Mustang". And we are attempting to provide full visibility into that release as it is being developed.

Every week we do an internal "promoted build" of the current Mustang sources. This gets a fairly rudimentary level of testing before it is released internally. Its main purpose is to provide a regular quasi-stable snapshot to our QA team which they can then use for their rolling QA test cycle. (Their full test cycle across all supported configurations takes five weeks, so they continually rotate in new weekly builds as they cycle through the test suite.)

After a fair amount of internal agonizing, we are now releasing these weekly builds on java.net in the mustang.dev.java.net [ http://mustang.dev.java.net/ ] project. We released build 12 last November and we have been updating the builds regularly since then. Why the agonizing? Well, the weekly builds can be pretty raw. Sometimes you will see the patient in mid-surgery, with the chest open and the internal organs in strange places. Don't panic! This is just a normal healthy development phase. We'll have everything back in place and sewed up neatly in a later build.

The weekly snapshots on mustang.dev.java.net [ http://mustang.dev.java.net/ ] include complete binaries, complete javadoc, and complete source. That includes all the Java library code, the associated native code, and the complete HotSpot JVM source code. So if you are interested in J2SE internals, it is all there to see, as the release develops.

Now, it must be said, we do have a stronger motivation than just satisfying people's intellectual curiosity. We are hoping that you won't stop with merely looking at the source code, but will move on to the next step...

Contributing Into Mustang

We are actively seeking source code contributions into Mustang.

Have a bug that has been irritating you for years? A little feature that you have sorely missed? Well now is the time to act!

To contribute into J2SE you need to accept the Sun Contributor Agreement [ http://jdk.dev.java.net/Sun_Contributor_Agreement.pdf ]. You keep all your rights to use your contribution yourself, so you can reuse you contribution elsewhere, but you also grant Sun rights to incorporate and use your source code contribution.

We are not opening the gates to unrestricted change here. We have fairly rigorous internal review processes to maintain code quality and to preserve cross-release compatibility. API changes get even more scrutiny (including JCP reviews). External contributions will be reviewed through the same processes. We do need to be very cautious - millions of developers are depending on J2SE and we take the physician's doctrine of "first, do no harm" very seriously.

Now some good news: several senior engineers from the J2SE team are actively working with potential contributors. They will navigate your changes through the internal review processes. But they need your help in getting the initial high-quality source contributions!

Like most community source projects, this will probably evolve into a pragmatic meritocracy. People who demonstrate competence and successful delivery will be trusted to take on increasingly larger tasks. We ask that new contributors start initially with small "safe" bug fixes, and then progressively work up to riskier fixes and then feature contributions.

What are we looking for? Well, we want more than just a bug report or a rough suggestion. Here's what we are looking for:

A clear description of the bug or feature that is being addressed.
A complete set of source changes that implement the bugfix or feature. (Preferably relative to a recent Mustang build.)
Unit test(s) that confirm the expected behavior.
An informal assurance that the code has been compiled and tested and seems to work.

More details on the source contribution process are available here [ http://mustang.dev.java.net/collaborate.html ].

Building Your Changes

Doing a complete build of the J2SE sources can be a daunting task. There are lots of environmental dependencies on native APIs, especially on Windows. But you don't need to do a full build in order to contribute a bugfix or feature; just compile and test the files you have changed. For Java code, you can compile the changed Java files and then use the Java -Xbootclasspath [ http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/java.html#nonstandard ] option to specify a new bootclasspath that that includes your changed classfiles as well as the regular rt.jar.

We are working to simplify the build, including making it work with a wider range of tools and compilers. This will roll out over the next few months. But you don't need to wait for that!

Why Are We Doing This?

So why are we making these changes?

This definitely isn't about cost reduction. Our development costs are dominated by the back-end processes: code reviews, integration, test development, release engineering, testing, and long-term maintenance. We expect it will take significant work on the Sun side to mentor contributors and integrate external fixes. Based on other experience, we expect that this project will increase our costs, not lower them. But there are two positive benefits that we believe will outweigh the costs.

First, the platform may benefit from external experience or perspectives that aren't in our internal team. A striking example of this would be Doug Lea's work on the JSR 166 Concurrency Utilities package in Tiger. We could have built an equivalent package internally, but Doug's experience and insight led to a much higher quality result. Using external expertise to improve the J2SE source code seems like a really good thing.

Second, allowing people to contribute fixes and features allows them to vote in the most direct and effective way. We are trying to prioritize both bugs and features across the needs of the whole J2SE community. We do our best to balance the various community needs, but sometimes we may not deliver some change that really matters to someone. If people are really willing to contribute their own time and energy to deliver a high quality fix or feature, then that is something we should accept and encourage.

Your Opportunity

This is your opportunity to contribute into the community and to help make the platform better. We definitely want to welcome new contributors and we will also be providing various mechanisms for recognizing key contributions. So you can make the world a better place and be publicly recognized for it too!

The doors are open. Source contributions are welcome. This is your chance to participate!