Apache Derby: Get Involved!

The Derby technology will grow and thrive from those who use it, so send the community your feedback:

• Subscribe to the Derby mail lists.
• Add your wisdom to the Derby Wiki.
• Derby uses Apache's Jira issue tracker to log bugs and enhancement requests. Anyone can browse the Jira database. To log new issues, see the tips page, which describes how to create a userid for yourself and how to log useful bugs. To update existing issues, email your Jira userid to derby-dev@db.apache.org and request that it be added to the derby-developers Jira list.
• Pre-built jar files are available on the Derby Downloads page.

The primary mechanism for Derby communication is the Derby mail lists. Anyone can participate, no matter what their time zone. The ASF maintains a reliable searchable archive of past discussions. Oversight is enabled. Many eyes ensures that the project evolves in a consistent direction. The main channel for development is the "derby-dev" mailing list, and the main channel for user support is the "derby-user" mailing list. As is usual with mailing lists, be prepared to wait for an answer.

The Derby community also maintains an IRC channel on the freenode IRC network. You are welcome to stop by:

/server irc.freenode.org /join #derby

However, keep in mind that all decisions occur on the Derby mail lists and not on IRC. Please summarize any off-list knowledge gained and post it for the benefit of all. For example, if a user asks a question and gets a response, post that exchange to derby-user. If developers work out a strategy for solving a problem, post a summary to derby-dev, including alternatives that were considered but ultimately dismissed and why. If developers figure out how something works, post a summary of the finding to derby-dev.

In all cases, additional eyes can catch any errors, point out any subtleties, and fill in additional information. The more discussions are on-list, the more the rest of the community will benefit from the understanding that is developed.

New users and developers who are familiar with how development occurs on commercial products sometimes get confused by open source development at Apache.

The first thing to understand is individuals volunteer for various tasks. Here are some relevant quotes from the How the ASF works page:

• "Projects are normally auto governing and driven by the people who volunteer for the job. This is sometimes referred to as "do-ocracy" -- power of those who do. This functions well for most cases."
• "All of the ASF including the board, the other officers, the committers, and the members, are participating as individuals. That is one strength of the ASF, affiliations do not cloud the personal contributions.
  Unless they specifically state otherwise, whatever they post on any mailing list is done *as themselves*. It is the individual point-of-view, wearing their personal hat and not as a mouthpiece for whatever company happens to be signing their paychecks right now, and not even as a director of the ASF."

However, lest it look like everybody is working diligently solely as an individual (and possibly at cross purposes with others), community coordination and contribution occurs on the Apache mail lists. The How the ASF works page provides helpful context.

So, Derby depends on the community to work together as a whole to change the product. How can new Derby users and developers actively participate in these changes?

First, open Jira issues to report problems you have stumbled upon or to request new features. However, remember that volunteers fix issues -- a valuable reminder from the ASF FAQ is below:

• What is Apache not about?
  • To [...] demand someone else to fix your bugs.

Second, vote on Jira issues that you feel strongly should be fixed.

Third, participate even more in the Derby development process by subscribing to derby-dev@db.apache.org. That's where core development discussions occur and decisions get made.

Fourth, if you want to actually start doing development, the next section is tailored specifically for you.

If you would like to participate directly in Derby development, here are a few guidelines:

• Like all Apache projects, the Derby project follows the Apache Way.
• Derby follows the guidelines established by the Apache DB Project.

Additional information for contributors is on the Derby Wiki. Below is just a sampling of the topics covered:

• For Developers: Information for Derby developers.
• For New Developers: Information to get started with Derby development.
• Derby Contributor Checklist: Tips for developers contributing code to Derby.
• Derby JUnit Testing and Derby Top-Level Tests: Information on running the various Derby test suites.
• Derby Commit Process: How a change to Derby actually gets committed.

The remainder of this section includes some miscellaneous tips that don't seem to have made it onto the Wiki (yet).

How to create a patch

1. Sync up your local svn copy with any changes checked into the server:

   cd <my_derby_loc>/trunk
   svn update
   

2. Make your change. If you are adding a new file, add it using svn. The example below shows adding a file named xyz.java:

   svn add java/engine/impl/yadiyadi/xyz.java 
   svn propset svn:eol-style native java/engine/impl/yadiyadi/xyz.java
   

3. Run the tests (for more details, see the wiki links above).

   ant all
   ant junitreport
   

   Resolve any test failures.

4. Make the patch.

   svn diff > xyz.diff
   

5. Attach the patch to the Jira issue.

   Include the following information with your post:

   • Which tests were run.
   • For a feature, a description of what the detailed functionality that is being implemented is essential.
   • A description of the changes, e.g. how a feature is implemented or why the change fixes a bug. Hopefully this will be in comments in the code but sometimes an overview in the e-mail is useful, or have the e-mail point to an overview in the code comments.
   • If the patch modifies more than one file then the output from 'svn status' is very useful to have in the e-mail.

Submit patches against the trunk

New features, code cleanup, performance fixes and other significant changes need to be submitted against the trunk.

Bug fixes may be submitted against either the trunk or a branch.

See the "Contributing with patches" mail list topic.

Enigmail tips for sending and saving patches

If you use Enigmail to send a patch to the derby-dev mail list be aware that, by default, Enigmail handles Mozilla's text=flowed formatting by replacing leading spaces with a tilde ("~") character (see http://enigmail.mozdev.org/troubles.html#flowed). To send a patch in-line using Enigmail, turn off the Allow flowed text setting:

     Enigmail -> Preferences -> Sending -> Allow flowed text (RFC 2646)

If you use Enigmail to save a patch submitted to the derby-dev mail list, you may need to decrypt and save that decrypted email if it was signed using gnuPG because lines that begin with a dash get escaped with "- " (see http://www.stillhq.com/extracted/gnupg-api/doc/faq.html#q4.7). To extract the text in Enigmail without the escape characters, first decrypt the email, then save the decrypted message:

     Enigmail -> Decrypt/verify
     Enigmail -> Save decrypted message