Apache Derby: Get Involved!
Welcome to the Derby community! We invite you to participate as a user or as a contributor -- or both!
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 email@example.com and request that it be added to the derby-developers Jira list.
- Pre-built jar files are available on the Derby Downloads page.
Use the Derby Communication Channels
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.
Understand How Development Works at Apache
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
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?
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 firstname.lastname@example.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.
Contribute Code or Documentation
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 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
Sync up your local svn copy with any changes checked into the server:
cd <my_derby_loc>/trunk svn update
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
Run the tests (to be safe, run derbyall). (Be sure to set your CLASSPATH env var to include the trunk/classes dir.)
ant all cd <a temp/test dir> java org.apache.derbyTesting.functionTests.harness.RunSuite derbyall
Resolve any test failures (update relevant ../functionTests/master/*.out files).
Make the patch.
svn diff > xyz.diff
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
Last updated: May 4, 2006