THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
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 OODT Community
OODT Development Roles
There are three main roles that a person can play in the OODT community.
The first role is that of user. This is someone who uses the OODT software but is not active in its development. People in this category range from the curious programmer who wants to learn more about grid technology to corporations setting up internal clouds. If you only want to use the OODT software and don't want to help develop it, you can still be a contributing member of the community. By using the software and pushing the limits of what it can do, by filing bug reports and feature requests (more about how to do this later), by working with developers to track down issues, or just giving your input to discussions that arise, you can help the OODT project become better and better.
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-ocracy, 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.
The third role is that of committer. This is usually a developer who has been working with the project for some time. Someone who has developed new pieces of functionality, who has fixed bugs, and who has helped others through answering questions and providing guidance to others through the mailing lists and wiki. In other words this is a person who has proved their commitment and usefulness to the project and in return are given commit access to the source code repository, an apache email address, and the ability to help make strategic decisions for the project by determining what submissions and bug fixes make it into the source code repository and release versions of the software.
How the Community Works
The community works together through shared mailing lists, email, wikis, bug tracking systems, and source code repositories. These tools when used together provide a virtual meeting room and workspace for all members of the community.
Mailing Lists and Email
Most communication is done through email and the mailing lists. Because of this the first thing that any person should do to become part of the OODT community is to join the appropriate mailing lists. There are four different mailing lists. The first is the user mailing list. This list is where most user communication occurs including general announcements. This is also where users can pose new ideas for functionality, provide general feedback, or ask for assistance. The second list is the dev mailing list. This is where most development communication occurs including updates to request tracking systems. The dev mailing list is important for tracking functionality that other developers may be working on and consensus by the community on desired direction of new features. The third list is the commit mailing lists. This list tracks commits to the source code repository and changes in the wiki pages. The fourth list is the private list, available to OODT committers and IPMC and mentor members.
Users can get by with subscribing to only the user@ mailing list. Developers should subscribe to dev@ list. In order to post to any list, for example to ask a questions, it is necessary to first be subscribed to that list. Below are links for subscribing to the different mailing lists.
user-subscribe@oodt.apache.org
dev-subscribe@oodt.apache.org
commits-subscribe@oodt.apache.org
private-subscribe@oodt.apache.org
JIRA and Issue/Request Tracking
If mailing lists provide the ongoing conversation for the community, the issue/request tracking system provides a repository for the current state of the project. The request tracking system is JIRA system and it can be accessed at this address: https://issues.apache.org/jira/browse/OODT.
The JIRA system is the central repository for all work wanting to be included int the OODT source code base. The system tracks issues and feature requests by component, by version, and by status. You can view what requests are assigned to what person, what requests are currently being worked on, and which ones haven't been scheduled. You can search all requests by keyword or by various categories and filters. We will go into detail later on how to use the JIRA system to propose new functionality and submit bug fixes. For now understand this: If you are going to be a developer you will need to understand how to use the JIRA system as this is where you will propose new functionality, submit bug fixes, give you input on features other developers may be working on, and coordinate actions with other developers on specific pieces of functionality.
The address to signup for JIRA was given above. Once you have signed up you will have access to all of the Apache JIRA repository, not just the OODT project.
Source Code Control through Subversion
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 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 taking patches from the JIRA system and applying them to subversion where they then become available to all users.
Wiki and Documentation
The weakest part of most open source projects is their documentation and OODT is no exception. Wikis are special web pages like the one that you are reading that allows users to directly edit text on the page and to create new pages. The wiki provides various tutorials and documentation for OODT. Links to view the OODT wiki and to register for the wiki are provided here: http://cwiki.apache.org/confluence/display/OODT.
As a developer one of the ways you can contribute back to the community is by documenting your hard won experience on the wiki. You can do this in the form of tutorials, articles, or simple notes and instructions. Anything that you have learned may be of use to other developers. The wiki is also used as a virtual white board to help document general themes and directions for the project.
These four tools, mailing lists and email, JIRA, Wikis, and Subversion together provide the community ways to coordinate their actions and conversations. As a developer you will need to understand each of these tools and how you will use them in the development process.
Next Steps
The rest of this document will cover four steps in becoming a OODT developer. First is using the mailing lists to communicate, find information, and get solutions to problems. Second is how to go about learning the different parts of the OODT codebase. Third is how to use the JIRA to search for bugs and coordinate development efforts. And four is how to use the wiki to help grow the community knowledge base.
Becoming a OODT Developer
Step One: Using the Mailing Lists
The most used tool in OODT development is by far the mailing lists. We have already explained the various mailing lists and their uses. This section will provide general guidance on using the mailing lists to find information and get questions answered.
First and foremost, any person wanting to become a OODT developer should start reading the user, dev, and commits lists on a daily basis. To start out with simply read the questions that other users ask on the users list. As you begin delving into the OODT codebase more and more you will be able to answer some of the questions that other users have. One of the best ways to learn OODT is by daily taking one question that is asked on the users list and seeing if you can find the answer.
As a developer you will want to keep up with the current state of development on the project and this is where the dev list comes in. The dev list is where JIRA messages will be delivered every time a JIRA request is updated. By following this list you will see discussions between other developers about various bugs and feature requests. You may also see an information voting occuring. If you feel you can contribute to one of the discussions, by all means add your input. You will also want to keep up to date on the commits list to see what code has been committed to the subversion repository and what updates have been made to the wiki.
Don't think that you have to be an expert on OODT to begin answering questions. If you think you can help another user on the mailing list, don't be afraid to go and do it. I think that it was Eric Raymond that said "Given enough eyeballs, all bugs are shallow". What this means is that you bring a unique perspective to the world as does everyone else and you may find bugs that no one else can find. The more people we have looking at the code and improving upon it, the more stable and robust it will become. The more people we have in the community constantly communicating, asking questions and helping each other, the better we all become.
As you start to have questions about the configuration and operation of OODT or about errors that you have received, go ahead and ask these questions on the user list. When asking questions it is best to provide a 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.
Before asking questions on the list you will want to search the list to see if your problem has come up in the past. There may already be a solution to your problem out there. There are plenty of times where questions are unanswered on the list because the same question had been answered only a few days before and the person asking never bothered to search the archives of the list.
Here are some other important things to remember about the mailing lists. First, do not cross post questions. Find the best list for your question and post it to that list only. Posting the same question to multiple lists (i.e. commits and dev) tends to annoy the very people you want help from. Second, remember that developers and committers have day jobs and deadlines also and that being rude, offensive, or aggressive is a sure way to get your posting ignored if not flamed.
Most questions on the lists are answered within a day. If you ask a question and it is not answered for a couple of days, do not repost the same question. Instead you may need to reword your question, provide more information, or give a better description in the subject.
Step Two: Learning the OODT Source Code
TBD
Step Three: Using the JIRA and Developing
Ok, so you have gone through the source code and have a good 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.
Now it is time to start browsing. JIRA provides a lot of search facilities. On the top of the main JIRA page there is a free text search. On the right hand side of the main JIRA page there are preset filters. You can search by status of the issue, by priority, or by assignee. You will want to try out each of the different search options to get familiar with the capabilities of JIRA.
When you do a search in JIRA you are presented with a listing of issues that match your query. The results listing will show you the JIRA id for the OODT issue. This is in the form of OODT-XXX. It is important to remember the JIRA id numbers as this is how you will reference issues that you are working on both through the JIRA and in communicating with other developers on the list. The listing also shows a brief summary of the issue, who it is assigned to, who reported it, the priority and status of the issue, and if it is resolved. Clicking on the issue number will bring you to the main page for that issue. The main issue page is where you will communicate with other developers about this issue and where you will attach your code patches for bug fixes and new feature requests. Whenever changes are made to JIRA issues an email is automatically generated and sent to the dev mailing list. You will have to be logged in to leave comments or to attach documents to issues. Again it is important to become familiar with the interface.
Once you have become familiar with the JIRA interface it is time to pick something to work on. If you already have something that you wish to work on, either a bug fix or a new piece of functionality then the first step is to send a message to the dev mailing list detailing the issue. By doing this you can get feedback from other developers. You may find that someone is already working on the issue or that the functionality is handled elsewhere. Either way first notifying the list, especially if it a major piece of new functionality, is the polite thing to do.
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 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.
Regarding the picking of the work to be done - natural ordering in JIRA should be followed. Issues marked critical are more important than "major", and the ones with a lot of votes are more important than those without any.
Once the JIRA is created and has been assigned to you then it is time to start coding. Remember to follow a few simple guidelines while coding.
- 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 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 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.
You 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.
Please do:
- try to adhere to the coding style of files you edit.
- comment code whose function or rationale is not obvious.
- update documentation (e.g., package.html files, this wiki, etc.)
Finally, patches should be attached to the JIRA issue. You can do this by logging into the JIRA issue and clicking the attach file to this issue link on the left hand side of the JIRA issue page.
Then please be patient and in the mean time start working on another issue. Committers are busy people too. If no one responds to your patch after a few days, please make friendly reminders to the dev mailing list. Please incorporate other's suggestions into into your patch if you think they're reasonable.
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 reasons but most often it is because the piece of functionality is not in 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.
Step Four: Contributing
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 lift each other higher.
Becoming an OODT Committer
So you have developed some very useful functionality and contributed it back to the community. You consistently fix bugs. You answer questions for other users and developers on the mailing lists. All in all you are an asset to the community. At this point you may be invited to become a committer. At this point you would get an apache email address and direct access to the subversion source code repository and you would be responsible for helping set the technical direction of the OODT project.
Conclusion
So I hope this tutorial has helped to guide you in the direction of becoming an OODT developer.
This page and guide is for the most part a rephrasing of the excellent guide written by Dennis Kubes, in the Apache Nutch project. Thanks, Dennis! Imitation is the worst (best!) form of flattery! 