Page History

Table of Contents

Overview

This document describes how to contribute to OODT. The purpose of this document is to help you as developers take the next step in becoming contributing members of the OODT community. We will cover a general overview of the OODT development process including the different pieces and how they fit together. We will cover how the community works and interacts, using the mailing lists to search for information and how to ask questions to ensure that they get answered. We will also cover how to go about learning the internals of the OODT codebase. We will cover how to use the JIRA for change requests and how to start developing for OODT. And finally we will cover contributing back to the OODT community. When we are finished you should have a good understanding of how the community works and how you can go about becoming a bigger part of that community.

...

The second role is that of developer. This is someone who has used the OODT software and has taken the next step to help program the underlying software. Since you are reading this document, it is assumed that you want to be a developer. Helping to develop the OODT codebase can come in the form of bug fixes or by developing completely new features from scratch. An important thing to remember is that unlike most software development at big companies, you don't need anyone's permission to start developing software for OODT. If you think you have a good idea for a feature, or if you want to track down and fix bugs in the software, go for it. If you want a specific piece of functionality, don't wait for someone else to develop it. Take the time to learn and develop it yourself. Then when you are done give it back to the community. This is how the OODT project has been developed so far and how it will continue to be developed in the future. The community is a do-ocrcyocracy, meaning those who do the work get to help set the directions and make the decisions. Communication is essential but not limiting. Anybody can become a developer simply by taking the initiative, whether in the form of fixes or functionality, for inclusion in the project.

...

Source code control is very important to open source projects. OODT uses the apache subversion repository for it source control. As a developer you will want to get into the habit of downloading and updated updating your development environment directly from the subversion repository. We will go into detail about how to do this later. There are two types of logins to the repository, users and committers. Users can download the repository but cannot make changes directly to the repository. You can make changes on your local system and those changes can be submitted to the JIRA system. Committers hold the committer role that we discussed previously. These individuals can make changes directly to the subversion repository and are responsible for take taking patches from the JIRA system and applying them to subversion where they then become available to all users.

...

As you start to have questions about the configuration and operation of OODT or about errors that you have recievedreceived, go ahead and ask these questions on the user list. When asking questions it is best to provide a descritive descriptive subject and detailed information about the problem or question. Detailed information would include snippets of log or configuration files and a good description of the problem. In general the more specific information you can provide, the easier it is for other users and developers to help.

...

Ok, so you have gone through the source code and have a good understand understanding of the different components. Now you want to start developing or fixing bugs. Where do you start. ? First if you haven't already signed up for the JIRA, do so now. Instructions were provided earlier for this.

...

Once you have gotten feedback from other developers and no one has objected then you will need to create an issue in the JIRA. In the JIRA issue please give as much detail and description as possible. Once the issue is created assign the issue to yourself or if you don't have permissions to do so then send a message to the dev mailing list asking that the issue be assigned to you.

If you are not creating an a new issue but instead want to begin working on an existing issue then here are the steps. First find the issue that you want to work on. If it is assigned to someone else then send a message to that person to see if they are working on it and where they are at in their process. It often happens that issues get assigned to developers but the developers are too busy to work on them. Or it may be that the person is in the process of working on the issue and would welcome your help. Either way, you should always contact that person and coordinate the efforts. That's only polite and sensible.

...

• All public classes and methods should have informative Javadoc comments.
• Code should be formatted according to Sun's conventions, with one exception: indent two spaces per level, not four.
• Contributions should pass existing unit tests.
• New junit test cases should be provided to demonstrate bugs bug fixes and new features.

You will also want to perform functional testing of your new code within your own environment as well as make sure that the and build and javadoc are successful with your new code. Once your code has been completed and tested then it is time to create a patch.

Start by checking to see what files you have modified with: svn stat.

Keep this list for later because you will want to make sure that only code that you have changed is included in your patch.

In order to create a patch, just type:

svn diff > yourPatchName.patchYou can follow the guide here: https://cwiki.apache.org/confluence/display/OODT/Steps+to+generate+patches

This will report all modifications done on the OODT sources on your local disk and save them into the yourPatchName.patch file. Read the patch file. Make sure it includes ONLY the modifications required to fix a single JIRA issue.

Please do not:

• reformat code unrelated to the bug being fixed: formatting changes should be separate patches/commits.
• comment out code that is now obsolete: just remove it.
• insert comments around each change, marking the change: folks can use subversion to figure out what's changed and by whom.
• make things public which are not required by end users.

...

Now here is the hard part. Even if you have completed your patch it may not make it into the final OODT codebase. This could be for any number of reason reasons but most often it is because the piece of functionality is not in lines line with the strategic goals of OODT. Of course if you had sent an email to the list before starting development on the issue then this would have already been addressed. Remember though that all developers have access to your functionality through the JIRA and they can and will use your patch even if it does not make it into release code. Every patch is useful to the community.

...

This is the easy step. As you get more and more understanding in the OODT code base. It is useful to take your hard earned knowledge and start helping others in the community. You can do this by creating tutorials, articles, and notes on the wiki or by answering questions on the mailing lists. Remember that the project is a circle. The more people you help the better they become and better functionality they develop that in turn helps you. Together we can all life lift each other higher.

Becoming an OODT Committer

...

This page and guide is for the most part a rephrasing of the excllent excellent guide written by Dennis Kubes, in the Apache Nutch project. Thanks, Dennis! Imitation is the worst (best!) form of flattery!