How to contribute to the Shoal project

This page describes the contribution process for the Shoal project.

0. Become a contributor

Like many other open-source projects, the Shoal 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 Shoal 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 Shoal project.

Request a Role through Role Request link.

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 "gms" 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.Use the Shoal Dev alias at dev@shoal.dev.java.net

They're likely to be able to offer comments and suggestions for 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

<Issue Number> : My favorite bug/RFE 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] <Issue Number>: My favorite bug/RFE synopsis

If no existing bug or RFE describes your change then omit the id number

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.
• Diffs of the code changes (cvs diff -u). Be sure to identify the baseline version for your diffs by mentioning its build number (b02, b03, etc.), which you can find in the name of the source bundle you that started with.
• A unit test 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, but if practical then a unit test is required.

4. Contribute through Code Reviews, Site Content and Documentation

Although much of the project code has associated javadoc comments, we welcome contributions where there aren't any.

We welcome code review comments posted through Issue Tracker or the Dev alias.

Any contributions for site content/maintenance and documentation of Project Shoal is also most welcome.